claude-tools-gateway
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-tools-gateway Start a read-only session to view ~/project/config.json"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Tools Native Gateway
In one sentence: Make web ChatGPT the sole brain, driving real local Claude Code native Sessions to perform controlled reads, modifications, verification, and recovery.
The public repository contains only source code and tests; it does not include local keys, Tunnel configuration, or state/ session state.
Architecture
The Gateway now has only one execution engine: Native V2.
当前 ChatGPT Chat(唯一主脑)
↔ Claude Tools Native MCP(六个 Session 控制工具)
↔ 本地模型回合桥(127.0.0.1)
↔ 隔离的 Claude Code 原生 Session
→ 原生 Agent loop
→ 网关自有的受控工具 ExecutorThe Gateway itself handles MCP initialization, tool inventory, and call dispatch; it no longer starts or proxies V1's claude mcp serve tool server. A Claude Code process dedicated to a Session is started only after the Native Session is created.
The original V1 Agent Session, top-level Read/Edit/Write/Bash, local task tools, legacy DeepSeek delegation, and ChatGPT Bridge have been removed from the runtime entry points and the code tree. What remains are the shared low-level facilities V2 still needs: atomic state writes, credential path protection, process identity verification, and macOS sandbox rules. Old V1 state files are not automatically deleted, but the Native Gateway will not read or execute them.
Related MCP server: claude-code-bridge-mcp
MCP Control Plane
The web version sees only six tools:
native_session_startnative_session_continuenative_session_recovernative_session_reply_and_waitnative_session_statusnative_session_stop
Any V1 tool name, top-level file tool, Bash, legacy DeepSeek tool, or other MCP method is rejected server-side, rather than merely hidden from the tool list.
Claude Code Session Capabilities
Sessions have three distinct tiers; after creation, they cannot be upgraded, downgraded, or have their root directory changed:
read_only:Read,FindFiles,SearchText, and read-onlyRunCommand; the read scope is the entire computer, except for protected state/credential paths and macOS permissions.direct_write: addsEdit,Write, andNotebookEditon top of full-computer read capability, modifying only the real directory the user explicitly selected. This tier should only be chosen when the user explicitly asks to modify real files.worktree_write: the tool set is the same asdirect_write, but modifications go to a separate Git worktree created and retained by the Gateway; the source checkout remains unchanged.
These are logical tools the model can call in Claude Code's native Agent loop, but the executors belong to the Gateway. Unregulated Claude Code built-in file tools and Bash remain disabled, to avoid bypassing action authorization, hashing, recovery, and the audit ledger.
Reading and Search
Readcan read any unprotected plain UTF-8 file on the computer, no longer restricted to the write directory.FindFilesperforms bounded file enumeration from any absolute directory.SearchTextdoes UTF-8 literal matching only; it does not accept regex or glob.Searches do not follow symbolic links and skip
.git, protected paths, and external hard links.Both a single search result and a full action receipt are limited to 64 KiB.
All tiers can inspect different disks and directories;
working_directoryis only the default search location, the command CWD, and the write boundary for write tiers. macOS TCC/file permissions may still deny Desktop, Documents, or other system-protected locations.
File and Notebook Modification
Under
direct_write,Edit,Write, andNotebookEditmodify the real directory bound to the Session; underworktree_write, they modify only the managed worktree.Writecan create missing parent directories on demand within the authorized root, then atomically create the target file; it cannot use this to escape the root, symbolic links,.git, or protected paths.NotebookEditsupports replacing, inserting, and deleting cells by cell ID, but does not execute the Notebook.Every write action saves pre-write and post-write SHA-256 and uses prepare, CAS, atomic persistence, and a durable receipt.
After a process crash, the real file state is verified; if it cannot be determined, recovery stops rather than blindly repeating the write.
direct_writehas no file deletion tool and does not write files because of read-only check commands; it may still overwrite or modify target files per explicit user instructions.In
worktree_write, the source checkout's files, HEAD, tree, index, and working tree state remain unchanged; the Git common dir registers a retained worktree.
Verification Commands
RunCommand accepts installed system commands and executables inside the Session directory; it no longer maintains a static command whitelist that could easily break normal development tools. Arguments are still passed as exact argv, never assembled into a shell string by the Gateway:
The Session root filesystem is read-only from the command's perspective;
Network, process signals, Keychain/XPC, and model CLIs are blocked by the macOS Seatbelt;
Entry points such as
sudo, direct delete/move, system control,find -delete/-exec,rg --pre, and model CLIs remain explicitly rejected;Symbolic links, hard links, or file counts in ordinary projects no longer cause the command to be rejected for the entire repository before startup; actual access is constrained by Seatbelt, protected paths, and macOS permissions;
Output, runtime, and subprocess group reclamation all have bounds;
Results first enter the same action ledger, then are handed to the next GPT turn.
It is intended for trusted repository verification, not as a container against malicious processes running under the same macOS account. Do not concurrently modify the managed worktree with other editors or processes while the Session is running.
Main Model, Web Search, and DeepSeek
The main route is fixed to chatgpt-main and does not accept model, provider, endpoint, API key, or fallback parameters. When the current ChatGPT turn stops, Claude Code pauses at waiting_for_gpt; it will not switch to Claude, DeepSeek, or Codex on its own to continue thinking.
Web search continues to be handled by web ChatGPT. Claude Code's WebSearch/WebFetch are not enabled, so there is no risk of GPT search conflicting with Claude's own search or of sources getting out of control.
By default, subagent_policy: "none" means no DeepSeek is created. Only after worktree_write explicitly selects deepseek_explicit can GPT use it in the main loop:
deepseek_subagent_startdeepseek_subagent_getdeepseek_subagent_stop
Delegation must first enter the main Session's persistent action ledger before the isolated sub-Session is allowed through. While a subtask is running, the main Session cannot concurrently Edit, Write, NotebookEdit, RunCommand, or start a second subtask. The route is fixed as Sonnet/Opus → Flash, Fable → Pro; failures do not fall back to Claude, Codex, OpenAI, or another DeepSeek tier.
Skill Context
native_session_start can accept up to eight skill_contexts explicitly selected by ChatGPT. They are not Claude Code's native Skill runtime:
Only the validated instruction body is extracted and frozen;
Scripts, resources, plugins, Hooks, Slash Commands, and extra tools are not loaded;
Each allowed item pins both the skill ID and the SHA-256 of the normalized full
SKILL.md;The first start and subsequent
resumeuse the same persistent snapshot;The full body appears only in 0600 private state and in the model context the current GPT turn requires.
Example allowlist:
CLAUDE_TOOLS_NATIVE_SKILL_ALLOWLIST_JSON='[{"skill_id":"personal:review","content_sha256":"<64位小写SHA-256>"}]' \
npm startThe hash is computed over the full text after removing the UTF-8 BOM and normalizing CRLF/CR to LF.
Isolation and Recovery
Each Session uses an independent HOME, Claude config directory, runtime directory, and process group.
Claude Code runs with
--bare, empty setting sources, strict MCP configuration, and a precise tool set.The main Claude process can only reach the exact local Broker/Executor loopback port.
Credential directories, Gateway state,
.git, symbolic links, and external hard links all fail closed; access to ordinary system/user paths is determined jointly by the Session root, macOS TCC, and file permissions.ChatGPT replies and each approved action are atomically persisted before being released to the running process.
Lease expiry stops the Runner and leaves an inspectable state.
A Gateway restart does not kill a Runner that still belongs to a Session;
native_session_recoververifies ownership, rotates the lease, and continues the same Claude Code Session.When the Runner no longer exists, recovery is not faked, and completed actions are not repeated.
Claude Code 2.1.247 has no verified standalone switch to "enable only Hooks while continuing to disable keychain, plugins, and automatic memory," so native Hooks, native Skill/Slash, Agent, Workflow, Web, and third-party MCP not governed by the action ledger remain disabled.
Running
npm startThe Native Gateway no longer needs the CLAUDE_TOOLS_NATIVE_V2 or CLAUDE_TOOLS_NATIVE_V2_ONLY switches; Native-only is the only runtime mode.
State is saved in state/ by default and can be changed via the absolute-path environment variable CLAUDE_TOOLS_STATE_DIR. The default Claude Code path is $HOME/.npm-global/bin/claude and can be overridden with CLAUDE_BIN.
Long-running Tunnel/Connector instances need to be restarted after source updates. ChatGPT may cache the connected tool schema; if a new session does not see the six native_session_* tools, refresh or reconnect the Claude Tools Connector.
Verification
npm test
npm run test:native:installed
npm run test:native:installed:write
npm run test:native:installed:direct-write
npm run test:native:installed:deepseek
npm run test:native:installed:skillsAutomated tests cover:
Native-only MCP direct initialization, the exact six tools, and rejection of V1 tools and unknown methods;
Turn and action ledger, reply idempotency, leases, process ownership, stop and recovery;
Read/FindFiles/SearchText full-computer reads, protected paths, size, ordering, literal matching, and race boundaries;
Edit/Write/NotebookEdit direct real-directory writes, worktree isolation, CAS, hashing, and crash recovery;
RunCommand permissive development command entry points, Session-local executables, read-only filesystem, zero network, sensitive service blocking, and timeout reclamation;
Skill ID/body hash pinning, start/resume consistency, and private state boundaries;
DeepSeek explicit delegation startup barrier, single-task write lock, route verification, Gateway restart recovery, and stop;
Public MCP/Session/history does not leak authorization IDs, Runner tokens, PIDs, internal paths, or model credentials.
Installed tests use the local Claude Code 2.1.247 and a localhost scripted GPT, without connecting to real models:
test:native:installed: executes FindFiles → literal SearchText → Read → final with/as the read-only root, and recovers the same Runner/Claude Session after the Gateway disconnects.test:native:installed:write: Read → Edit → Write → NotebookEdit → RunCommand → resume → Read.test:native:installed:direct-write: the same set of real Claude Code turns directly modifies a real directory in the test fixture, then resumes and verifies the persisted results.test:native:installed:deepseek: uses a local fake DeepSeek CLI to verify explicit delegation, result verification, active write lock, restart recovery, and stop.test:native:installed:skills: verifies that two hash-pinned, instruction-only Skills use the same snapshot across start/resume.
These local scripted tests do not consume real ChatGPT, Claude, or DeepSeek model quota. A real DeepSeek minimal smoke test still requires separate user authorization.
Available Tools
6 toolsnative_session_continueAIdempotent
Continue the same durable native Claude Code session without changing its immutable capability profile or filesystem root. ChatGPT remains the sole main model. A direct_write Session continues to address the same real directory; a worktree_write Session continues in its retained managed worktree. A Session created with deepseek_explicit may inspect or stop its explicitly started DeepSeek subagent; the subagent never takes over the main loop.
Inputs: prompt (required), lease_id (required), idempotency_key (required), native_session_id (required), +1 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
native_session_recoverBIdempotent
Reconnect ChatGPT to a durable native Claude Code session and rotate its lease. ChatGPT remains the sole main model. Any DeepSeek access remains limited to the Session's original explicit subagent policy; a write session is accepted only after its original direct directory or retained managed worktree binding is verified.
Inputs: recovery_id (required), recovery_token (required), native_session_id (required), wait_seconds. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
native_session_reply_and_waitADestructiveIdempotent
Submit ChatGPT's response for one exact pending native turn. ChatGPT is always the sole main model. Every profile permits bounded whole-computer Read, FindFiles, literal SearchText, and a network-blocked, filesystem-read-only RunCommand except on protected credential/state paths. direct_write permits gateway-authorized Edit, Write, and NotebookEdit only inside the selected real write root. worktree_write permits the same mutations only inside its retained managed worktree. A Session created with deepseek_explicit may additionally start, inspect, or stop one explicit DeepSeek subagent; start must be the only call in that response.
Inputs: turn_id (required), lease_id (required), reply_id (required), native_session_id (required), +2 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
native_session_startAIdempotent
Start an isolated native Claude Code session with the current ChatGPT conversation as the sole main model. subagent_policy defaults to none. All profiles may use Read, FindFiles, literal SearchText, and a network-blocked, filesystem-read-only RunCommand across the computer except protected credential/state paths. working_directory remains the command CWD and, for write profiles, the only write root. read_only never writes. When the user explicitly asks to modify the actual files in working_directory, choose direct_write; it works for Git and non-Git directories. Choose worktree_write only for an isolated copy of a clean Git repository. deepseek_explicit remains available only with worktree_write; DeepSeek never becomes the main model.
Inputs: prompt (required), idempotency_key (required), working_directory (required), wait_seconds, +4 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
native_session_statusARead-onlyIdempotent
Read native-session state without advancing it or invoking a model. ChatGPT remains the sole main model. Safe summaries of any explicitly enabled DeepSeek subagent and the retained managed-worktree location are returned when present.
Inputs: lease_id (required), native_session_id (required), wait_seconds. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
native_session_stopADestructiveIdempotent
Stop the isolated native-session process and preserve durable state and any managed worktree for inspection. ChatGPT remains the sole main model. Any active Session-owned DeepSeek subagent must be safely stopped and durably observed before the Session can finalize.
Inputs: lease_id (required), request_id (required), native_session_id (required), reason. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct lifecycle action such as start, continue, recover, reply, status, or stop. The only mild ambiguity is between continue and recover, since both involve reconnecting to an existing session, though the descriptions differentiate them by lease rotation and capability immutability.
All tool names follow the same native_session_ prefix with an imperative verb or verb phrase. The naming pattern is uniform and predictable, making the tool set easy to navigate.
Six tools is well-scoped for a session gateway: creation, continuation, recovery, interaction, status inspection, and shutdown. Each tool has a clear role without redundancy.
The tool set covers the full lifecycle of a native session: start it, continue or recover it, send replies, check status, and stop it. Stop preserves durable state rather than losing it, so the workflows do not end in a dead end.
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides comprehensive session management for Claude Code with automatic initialization/cleanup, quality checkpoints, and local conversation memory with semantic search for capturing learnings across coding sessions.6338 PyPI4BSD 3-Clause
- AlicenseNot gradedqualityDmaintenanceBridges Claude Code terminal sessions with Claude Chat by exposing session logs as tools, enabling seamless context transfer and two-way communication via a cooperative inbox and optional Google Drive sync.127 npm2MIT
- AlicenseNot gradedqualityBmaintenanceA secure, local-first MCP coding and computer-use harness for ChatGPT and Codex, enabling guarded file operations, durable terminals, Git review, local skills, and macOS computer control.142 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables voice assistants to start, monitor, message, and approve local Claude Code sessions on your computer, including sessions already open in a terminal. It exposes session management, recaps, approvals, and history search as MCP tools.7GPL 3.0