# 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](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels),
the MCP server stays private. `tunnel-client` makes an outbound HTTPS connection,
forwards MCP requests locally, and returns the results through the same tunnel.

## 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:

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

Or with `pipx` after cloning:

```bash
pipx install .
```

## Check a workspace

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

## Run as a standard stdio MCP server

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

The same values can be supplied through environment variables:

```bash
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:

```bash
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](https://platform.openai.com/settings/organization/tunnels).
Install the latest official `tunnel-client` from the Platform download link or the
[OpenAI tunnel-client releases](https://github.com/openai/tunnel-client/releases).

Following the official stdio profile flow:

```bash
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](https://chatgpt.com/plugins), 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:

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

See [Proxy and restricted-network setup](docs/proxy.md) for the reverse-SSH pattern
used when the proxy is on another machine.

## Example prompts

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

```text
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

```bash
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