Remote Workspace MCP

Connect a private filesystem workspace to MCP clients such as ChatGPT without uploading the repository or opening an inbound firewall port.

The server exposes six read-only tools:

• workspace_info — show the active root, policy, and limits

• list_projects — list top-level directories

• list_tree — inspect a bounded directory tree

• file_info — inspect file or directory metadata

• read_file — read a bounded range from a text file

• search_text — search text recursively with a filename glob

It deliberately has no write, delete, shell, or process-execution tools.

Why this exists

Uploading a large research or engineering workspace to ChatGPT is slow and quickly becomes stale. Remote Workspace MCP keeps the files where they already live and lets an MCP client retrieve only the directory entries, source ranges, and search results needed for the current question.

When paired with OpenAI Secure MCP Tunnel, the MCP server stays private. tunnel-client makes an outbound HTTPS connection, forwards MCP requests locally, and returns the results through the same tunnel.

Related MCP server: permission-aware-mcp

Requirements

• Python 3.10+

• An MCP client, or an OpenAI account with access to Secure MCP Tunnel

• For ChatGPT: developer mode and a tunnel associated with the target ChatGPT workspace

Install

From a clone:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Or with pipx after cloning:

pipx install .

Check a workspace

remote-workspace-mcp check \
  --root /home/user/projects \
  --policy project

Run as a standard stdio MCP server

remote-workspace-mcp serve \
  --root /home/user/projects \
  --policy project

The same values can be supplied through environment variables:

export REMOTE_WORKSPACE_ROOT=/home/user/projects
export REMOTE_WORKSPACE_POLICY=project
export REMOTE_WORKSPACE_MAX_READ_BYTES=8000000
export REMOTE_WORKSPACE_MAX_RESULT_CHARS=100000
remote-workspace-mcp serve

Access policies

project is the default. It omits common VCS internals, virtual environments, caches, dependency trees, and secret-like filenames. Source code, data directories, model directories, checkpoints, weights, and experiment outputs remain visible.

open exposes all names beneath the configured root. Path traversal and symlink escape are still rejected, and known binary formats are metadata-only:

remote-workspace-mcp serve --root /srv/workspace --policy open

Connect through OpenAI Secure MCP Tunnel

Do not commit a runtime API key or tunnel profile. Each user creates a tunnel and runtime key in Platform tunnel settings. Install the latest official tunnel-client from the Platform download link or the OpenAI tunnel-client releases.

Following the official stdio profile flow:

export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile remote-workspace \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "remote-workspace-mcp serve --root /home/user/projects --policy project"

tunnel-client doctor --profile remote-workspace --explain
tunnel-client run --profile remote-workspace

Keep tunnel-client run alive while using the connector. In ChatGPT, open the Plugins page, create a developer-mode MCP app, choose Tunnel, and select or paste the tunnel ID.

Secure MCP Tunnel is intended for private connections and developer-mode testing. It is not itself a public plugin distribution mechanism; public plugins require a stable public HTTPS MCP endpoint.

Outbound proxy

If the host cannot reach api.openai.com:443 directly, tunnel-client supports an explicit outbound proxy:

export TUNNEL_CLIENT_HTTP_PROXY=http://127.0.0.1:7890
tunnel-client run --profile remote-workspace

See Proxy and restricted-network setup for the reverse-SSH pattern used when the proxy is on another machine.

Example prompts

Use the remote workspace connector. Call workspace_info first, then list_projects.
Summarize the available projects without modifying anything.

Search the workspace for "mixed precision" in Markdown and Python files. Read the
most relevant files and explain how the implementation is organized, citing paths.

Development

python -m pip install -e '.[dev]'
ruff check .
pytest -q

Non-goals

• Remote shell access

• Editing or deleting files

• Running project code

• Replacing authentication or authorization at the workspace boundary

• Bundling OpenAI credentials or the tunnel-client binary

License

MIT