Secure Local Workspace MCP

English | 中文（默认）

Let the ChatGPT web version securely connect to local projects: whether or not Git is used, you can view, search, and modify files, and run whitelisted tasks; Git projects can also check diffs, create local commits, and push to a specified remote and branch after explicit user authorization.

You don't need to install Codex. ChatGPT calls the MCP service still running on your computer through the OpenAI Secure MCP Tunnel; the project directory and MCP port don't need to be exposed to the public internet.

Choose Your Use Case First

Related MCP server: Kastor

What You Get

The project does not provide arbitrary Shell, git add ., force push, history rewriting, production deployment, or arbitrary disk access.

First-time Installation: Connect to ChatGPT from Scratch

The following flow uses Windows PowerShell as an example. Usually only needs to be done once.

Step 1: Check Prerequisites

You need:

• Windows PowerShell;

• Git;

• Node.js 20 or higher;

• Access to ChatGPT developer mode;

• Permissions required for Tunnel in OpenAI Platform.

Check local commands:

git --version
node --version
npm --version

If you plan to let ChatGPT create Git commits, you also need to set up your Git identity first. If already set, you can skip:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Step 2: Download the Project

git clone https://github.com/dxawdc/secure-local-workspace-mcp.git
Set-Location .\secure-local-workspace-mcp

Step 3: Prepare the Tunnel on the OpenAI Page

Follow the OpenAI Secure MCP Tunnel official documentation to complete the following:

1. Create a Tunnel in OpenAI Platform;

2. Associate the Tunnel with the ChatGPT workspace that will use it;

3. Create a Runtime API Key for tunnel-client;

4. Download the latest official tunnel-client;

5. Record the tunnel_id and the local path of tunnel-client.exe.

These steps involve account permissions and keys and must be confirmed by the user on the OpenAI page; the project will not create or read account credentials on your behalf.

Step 4: Save the Runtime Key Outside the Repository

Don't write the Key into the README, project config, Git, or PowerShell command history. You can first create a file outside the repository:

New-Item -ItemType Directory -Path "C:\Secrets" -Force
notepad "C:\Secrets\openai-tunnel-runtime-key.txt"

Paste the Runtime Key in Notepad, keep only one line, save, and close. For production or team environments, switch to an organization-approved key management solution and restrict access to this file.

Step 5: Run One-click Configuration

Replace the three paths and Tunnel ID in the example with your own values:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -TunnelId "tunnel_REPLACEME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -RegisterStartup `
  -StartTunnel

How to fill in the parameters:

• ProjectRoot: the project directory you want ChatGPT to operate on this time; it doesn't have to be a Git repository;

• DiscoveryRoot: the parent directory where ChatGPT is allowed to discover projects, usually the parent of ProjectRoot;

• TunnelId: the real tunnel_id shown in OpenAI Platform;

• TunnelClient: the downloaded and extracted tunnel-client.exe;

• ControlPlaneApiKeyRef: the Runtime Key file path, must have the file: prefix.

The script will automatically complete:

1. Install Node.js dependencies using the lock file;

2. Run unit tests and MCP smoke tests;

3. Set the project to read-write and allow local commits;

4. Approve the project discovery directory;

5. Automatically identify test, lint, build, typecheck in package.json;

6. Create and check the Tunnel profile;

7. Register a login auto-start task for the current user and start the Tunnel immediately.

Push is not allowed by default. Non-Git projects automatically retain file read-write capability while forcibly disabling commit and push; no need to manually add -DisableCommit.

If accessing OpenAI from this machine must go through a proxy, append at the end of the command:

-HttpProxy "http://127.0.0.1:7890"

Step 6: Create a Private App in ChatGPT

1. Enable developer mode in ChatGPT settings. Enterprise/Edu users may need administrator authorization;

2. Open ChatGPT Plugins;

3. Click the plus sign to create a developer mode app;

4. Connection: select Tunnel;

5. Select the Tunnel you just created, or paste the real tunnel_id;

6. Create the app and wait for ChatGPT to discover the tools.

The official instructions require tunnel-client to keep running; otherwise ChatGPT cannot discover or call the tools.

Step 7: Verify the Connection

In a new ChatGPT conversation, select or @ this app, then send:

调用 diagnostics 和 list_projects。
告诉我 Tunnel 后面的本地 MCP 是否正常，并列出已授权项目、读写权限、commit 权限和 push 权限。
不要修改任何文件。

Under normal circumstances you should see the project list, and the default allowPush should be false. The new version provides 17 tools in total; if the old tools are still showing, restart the Tunnel and refresh the app in ChatGPT or start a new conversation.

Already Have a Tunnel: Add a New Project

If both the Tunnel and the login auto-start task were configured through this project, run in the repository directory:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\another-app" `
  -DiscoveryRoot "D:\Projects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

This adds or updates the project configuration without overwriting other authorized projects.

If you did not register the login task through this project, remove -RestartTunnel; after configuration is complete, restart tunnel-client the way you did before. After restarting, refresh the tools in the ChatGPT app settings.

Let ChatGPT Automatically Connect Non-Git Projects

Common Node.js, Python, Java, Go, Rust, .NET, PHP, Ruby, Elixir, Swift, CMake and other project directories will be automatically recognized by discover_projects. Even if a directory has no common project markers, it can still be connected via an explicit absolute path within the approved DiscoveryRoot:

调用 discover_projects，列出已批准目录中的 Git 和非 Git 项目。
把 D:\Projects\notes-app 接入为可读写项目。
如果它不是 Git 仓库，必须自动关闭 commit 和 push。
接入后调用 list_projects，确认 projectType 和最终权限。

After ChatGPT calls connect_project, the configuration is persisted immediately and takes effect in the current MCP process; no need to restart the Tunnel again for a single project.

View Only, No Modifications

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\reference-project" `
  -DiscoveryRoot "D:\Projects" `
  -ReadOnly `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Allow Modifications, But Not Commits

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -DisableCommit `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Only Add a Discoverable Project Parent Directory

.\scripts\quick-setup.ps1 `
  -DiscoveryRoot "E:\OtherProjects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Don't set DiscoveryRoot to the disk root, the entire user directory, or a directory containing large amounts of private files. It should be a parent directory dedicated to storing code repositories.

Daily-use Prompts

The project name is based on the ID returned by list_projects. The following prompts can be copied directly into ChatGPT, then replace the project name and requirements.

1. View and Analyze Only

使用 Secure Local Workspace MCP 检查项目 my-app。
先调用 list_projects 确认项目，再查看与登录流程有关的代码。
解释实现和可能的问题，不要修改文件，不要提交。

2. Modify and Test, But Don't Commit

检查项目 my-app 的重复提交问题并完成修复。
修改前重新读取目标文件并使用最新 SHA-256，只改与本次问题有关的文件。
运行项目允许的 test 或 lint 任务，最后展示 git_status 和 git_diff。
不要 commit，不要 push。

3. Modify, Test, and Create a Local Commit

修复项目 my-app 的重复提交问题。
运行相关测试，然后展示完整 git_diff 和 git_status。
确认差异只包含本次修改后，使用最新 statusSha256，
只提交本次涉及的明确文件，提交信息为：fix: prevent duplicate submissions。
提交后报告本地 commit SHA。不要 push。

4. Only Commit Changes Already Completed

检查项目 my-app 当前 git_status 和 git_diff，不要继续改代码。
如果存在与本任务无关或已经预暂存的文件，停止并告诉我。
否则使用最新 statusSha256，只提交这些明确文件：src/example.js、test/example.test.js。
提交信息为：fix: handle duplicate submissions。不要 push。

git_commit will reject:

• ., directories, or paths outside the project;

• Git status that has changed after review;

• Pre-existing staged changes;

• Sensitive paths such as .env, private keys, certificates, password stores;

• High-confidence API Keys, Tokens, private keys, or real Tunnel/organization identifiers;

• git diff --cached --check failures;

• Commit not enabled in the local configuration.

A successful commit only means it has been committed locally, not that it has been pushed.

Enable Controlled Push Separately

Push is an external write operation, so it must be explicitly enabled on this machine for the project. It is recommended to also restrict the target branch:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -AllowPush `
  -AllowedRemote "origin" `
  -AllowedBranch "main" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Then explicitly request it in ChatGPT:

检查项目 my-app 当前分支、HEAD、git_status 和待推送 commit。
只有在工作区状态和 commit 都符合预期时，才把当前 HEAD 推送到允许的 origin/main。
禁止 force push。分别报告本地 commit SHA、远端分支和推送结果。

git_push will not automatically create a commit, nor will it push to an unconfigured remote or branch.

Automation vs. Manual Operation Boundaries

For more detailed batch configuration, proxy, auto-start, rollback, and unattended references, see: Windows Automation Configuration Guide.

Configuration Management

The default configuration file is located outside the repository:

%USERPROFILE%\.secure-local-workspace-mcp\config.json

If the new-version configuration doesn't exist, the service will compatibly read the old path:

%USERPROFILE%\.local-project-workspace\config.json

View the current configuration:

npm run config -- list

When not using PowerShell automation, you can also call the cross-platform configuration CLI:

npm run config -- add-discovery-root --root "D:\Projects"

npm run config -- add-project `
  --root "D:\Projects\my-app" `
  --writable `
  --allow-commit `
  --no-push

The compatible script bootstrap-config.ps1 also idempotently adds or updates a single project without replacing the entire configuration.

Updating the Project

Set-Location .\secure-local-workspace-mcp
git pull --ff-only
npm ci
npm test
npm run smoke:mcp

After code or tool definitions are updated, you must restart tunnel-client and refresh the app in ChatGPT or start a new conversation.

Revoking Project Access

Send in ChatGPT:

调用 disconnect_project 撤销项目 my-app 的 MCP 访问权限，然后重新列出项目。

This only deletes the local authorization configuration; it does not delete the project directory, files, or Git history.

To remove the login auto-start task:

Stop-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel"
Unregister-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel" -Confirm:$false

This does not delete the Tunnel, Runtime Key, profile, or project files.

FAQ

Git commit identity is missing

First set the Git username and email, then re-run the configuration:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Scheduled task not found

You used -RestartTunnel, but the Tunnel was not registered through this project. Remove that parameter to complete the project configuration, then restart tunnel-client the way you did before.

Can't see the Tunnel in ChatGPT

Check in order:

1. Whether the Tunnel is associated with the current ChatGPT workspace, not just the Platform organization;

2. Whether the current account has Tunnels Read + Use;

3. Whether ChatGPT developer mode is enabled;

4. Whether tunnel-client is still running and in a healthy/ready state.

ChatGPT Didn't Discover the 17 Tools

• Restart the Tunnel runtime;

• Run tunnel-client doctor --profile <profile> --explain;

• Refresh in the ChatGPT app settings;

• Start a new ChatGPT conversation to avoid old sessions continuing to use cached tool definitions.

Project Can't Be Discovered or Connected

• The project must be within an approved DiscoveryRoot;

• Git repositories and non-Git directories containing common project markers will automatically appear in discovery results;

• Ordinary directories without project markers won't be listed automatically, but you can have ChatGPT call connect_project with their explicit absolute path;

• Non-Git projects will show projectType: non-git and have commit and push forcibly disabled;

• Run npm run config -- list to check the actual configuration;

• Re-add the parent directory and restart the Tunnel if needed.

Writes Rejected or SHA Expired

• The project must allow writes;

• Before modifying or deleting an existing file, ChatGPT must re-call read_file;

• After a file is modified by another program, the old SHA becomes invalid; this is normal concurrency protection.

Commit Rejected Due to Existing Staged Changes

First have ChatGPT call git_status to check. When you confirm it's safe to unstage, call git_unstage to handle the explicit files; this operation does not discard working directory content.

Tunnel Works Locally, But ChatGPT Calls Time Out

• Check outbound connectivity to api.openai.com:443;

• The browser being able to use a proxy doesn't mean tunnel-client automatically uses the same proxy;

• Write the proxy in via -HttpProxy during initial configuration;

• Check the local firewall, proxy certificates, and organizational network policies.

Local Verification

npm ci
npm test
npm run smoke:mcp
npm audit --omit=dev

Local MCP foreground startup:

.\scripts\start-local.ps1

The Tunnel status should at least satisfy:

process_running = true
healthy = true
ready = true

Security Recommendations

• Discovery Root should be a dedicated project parent directory; don't use the disk root or the entire user directory;

• Prefer enabling only commit; enable push per project, remote, and branch only when truly needed;

• Runtime Key, Tunnel profile, real configuration, and logs must be stored outside the repository;

• MCP commit temporarily disables project Git hooks; testing and formatting should be run through the explicit task whitelist;

• Still verify the explicit commit SHA, remote, and branch before pushing;

• If a key is accidentally committed, revoke it immediately and clean the complete Git history.

For security design and vulnerability reporting, see SECURITY.md.

Official References

• OpenAI Secure MCP Tunnel

• OpenAI MCP and Connectors

License

MIT