# Mcpx Chatgpt Vps Workspace

> Deploy and connect a scoped MCPX VPS workspace to ChatGPT through a Secure MCP Tunnel, with confirmation-gated browser setup and restart-safe verification.

- Skill: `ke971225-prog/mcpx-chatgpt-vps-workspace` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ke971225-prog/mcpx-chatgpt-vps-workspace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ke971225-prog/mcpx-chatgpt-vps-workspace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ke971225-prog (https://skillmd.com/u/ke971225-prog)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ke971225-prog/mcpx-chatgpt-vps-workspace

---


# MCPX ChatGPT VPS 工作区

Use this skill when the user wants ChatGPT or Codex to inspect, edit, execute, or operate files on a private Linux VPS through MCPX, including creation of the OpenAI Secure MCP Tunnel, runtime Key, and ChatGPT custom app. It also applies when a previously working workspace reports `remote session not found`, `ExceptionGroup`, `TaskGroup`, directory overload, or path/drive migration errors.

This skill creates a durable connection workflow, not a public file server. The intended path is:

```text
ChatGPT custom app → OpenAI Secure MCP Tunnel → tunnel-client (outbound HTTPS on VPS)
  → loopback MCPX → explicitly registered remote workspace
```

## Mandatory first response

Before any external mutation, inspect the target and output a compact but sufficient preflight report. Include:

- target host/provider, OS/architecture, RAM/disk, SSH port and authentication method;
- the exact remote workspace root and whether it is local, VPS, mounted, copied, or symlinked;
- the proposed MCPX, tunnel, runtime Key, and ChatGPT app names;
- what will be created/changed, what will remain untouched, and whether files or secrets will be copied;
- historical risks relevant to this target: Workspace registration, Remote Session, Tunnel online, ChatGPT app/tool access, path migration, unbounded directory reads, and startup persistence;
- verification gates and the exact items that remain unverified.

Then ask for one explicit confirmation immediately before creating the tunnel, runtime Key, app, changing SSH authentication, copying files, or deploying services. A prior request to inspect or explain is not authorization for those mutations. If the user confirms a narrower subset, execute only that subset.

Use the user-facing closing question `是否确认一键处理？` after the preflight. Treat `确认一键处理` (or an equally unambiguous confirmation naming the exact scope) as the gate; do not treat a vague “看看”“继续分析” or a browser page being open as authorization.

If the user asks for read-only diagnosis, do not create or alter anything. If credentials are supplied, use them only in an interactive or stdin-protected command, never echo, log, commit, or put them in this skill.

## Operating modes and token-efficient execution

Select the smallest mode that satisfies the request:

- **Inspect**: collect bounded host, service, workspace, tunnel, app, session, and tool-discovery evidence. Do not mutate.
- **Deploy**: after the preflight and explicit confirmation, install or repair MCPX, `tunnel-client`, systemd persistence, Runtime API Key handling, Secure Tunnel binding, and the ChatGPT app.
- **Recover**: diagnose one known failure such as `remote session not found`, `ExceptionGroup`, a migrated path, stale tool definitions, or a post-restart disconnect. Recheck only the affected gates first, then broaden if needed.
- **Operate**: use an already verified app/session to perform a narrowly scoped read, edit, or bounded command. Ask for a separate confirmation for consequential writes, publication, deletion/move-out, credential use, or payment.

Keep the workflow token-efficient without weakening verification:

1. Load only the reference needed for the selected mode; do not paste all references into the conversation.
2. Start with a compact preflight and bounded inventory. Never recursively dump a large workspace or repeat a failed full-root call.
3. Reuse stable aliases, versions, and previously observed gate results, but recheck drift-sensitive facts such as service state, endpoint, app snapshot, session ID, and path.
4. Prefer one focused tool call with a bounded result over many speculative retries. If a call fails twice with the same class of error, classify the gate and stop rather than generating more context.
5. End with a gate matrix: observed PASS, PARTIAL, BLOCKED, and still-unverified. This prevents later runs from rediscovering the same facts.

This can reduce repeated prompt/context and unnecessary tool-call overhead. It does **not** make model inference or tool use free, guarantee a fixed token reduction, or bypass the account's ChatGPT/Codex allowance.

## Shareable-package contract

This skill is intended to be copied to another Codex installation or published as a repository. Keep the package portable:

- use placeholders for hosts, paths, workspace IDs, organization IDs, app IDs, and service names unless they are generic examples;
- never include passwords, Runtime API Keys, SSH private keys, cookies, full `.env` contents, or run ledgers from a real deployment;
- describe current OpenAI plan/model behavior as time-sensitive and link to the official documentation rather than treating it as a permanent guarantee;
- preserve the distinction between a local Skill, a remote MCPX service, a Secure MCP Tunnel, and a ChatGPT custom app;
- before a public mirror, run a secret scan, remove operational history, validate the Skill, and add a license chosen by the maintainer.

The repository-level installation and teaching examples are in [README.md](README.md). Read the browser reference only when a ChatGPT app must be created, enabled, refreshed, or tested.

## Required execution rules

1. Read the project `AGENTS.md`, relevant `.learnings` files, and the historical reference below before acting. Preserve existing user changes.
2. Reuse the user’s already-open, signed-in Codex left-side in-app browser when available. Use the in-app browser skill and a persistent `getForUrl` binding; do not ask the user to paste browser cookies or tokens. If the page is signed out or the required Business workspace/role is absent, stop at that gate.
3. Use official OpenAI Secure MCP Tunnel documentation and the exact upstream MCPX release metadata. Verify release asset names and checksums; never assume `.tar.gz` versus `.zip`.
4. Keep MCPX on loopback. Do not open port 9090 or expose `auth.mode: open` to the public internet. Use a bearer/OAuth/dual mode if the MCP server has any public ingress. Default mutating MCPX commands to confirmation and preserve SHA/revision guards.
5. Treat `CONTROL_PLANE_API_KEY` as a runtime credential, not an admin credential. Create it from Runtime API keys, capture it only once, transfer it through an echo-disabled SSH stdin path, store it remotely with mode `0600`, and never print or save the value locally.
6. Configure both MCPX and `tunnel-client` as `systemd` services with `enabled`, `Restart=always`, and an explicit dependency from the tunnel client to MCPX. Verify after a restart when the user requests durable operation.
7. Do not claim “ChatGPT can access or edit the workspace” from a healthy process alone. Report these gates separately: MCPX protocol handshake, tunnel-client health/online, tunnel bound to the intended organization/workspace, ChatGPT app created/enabled, tool discovery, and an actual scoped read or edit call.
8. Never recursively dump a large workspace into one MCP call. Register the root, create/resume a Remote Session, then read with bounded pagination and selective paths. Do not delete “unused” files because a listing is large; classify first and use MCPX `move_out` prepare → user confirmation → submit for removals.
9. After each meaningful run, append a redacted history record with target alias, versions, changed resources, checks, errors, resolution, and unresolved gates. Use the supplied recorder; never include passwords, runtime Keys, SSH private keys, cookies, or full `.env` contents.

## Scope and credential boundary

The remote workspace is not automatically the user's local workspace root. Copy or mount only the explicitly selected project. By default exclude `.env*`, credentials, private keys, cookies, caches, `node_modules`, `.git`, build outputs, virtual environments, and other generated data from transfer and indexing; if a task genuinely requires a secret-backed publish operation, name the exact secret and target, explain the exposure, and obtain separate confirmation.

For MCPX, `edit` is for create/update/rename with revision guards. Deletion is not a direct edit: use `move_out` with a prepared manifest, show the targets and hashes, obtain the user’s confirmation, then submit. `execute` must have a concrete purpose, scope, and bounded command; do not treat an enabled tool as permission to run arbitrary commands.

## Reference routing

- Read [deployment-runbook.md](references/deployment-runbook.md) for the VPS, MCPX, tunnel-client, systemd, key, tunnel, and app sequence.
- Read [chatgpt-browser-flow.md](references/chatgpt-browser-flow.md) when the user has ChatGPT open or asks for automatic app creation/enablement.
- Read [history-and-errors.md](references/history-and-errors.md) before diagnosing sessions, directory overload, migrated folders, or the known historical failures.
- Run `scripts/preflight_workspace.py` before a broad workspace read or transfer. It is read-only and intentionally bounded.
- Run `scripts/record_run.py` after a run to append a redacted JSONL handoff record.

## Completion language

Use `PASS` only for an observed check. Use `PARTIAL` when the tunnel or app exists but a real ChatGPT tool call is not verified. Use `BLOCKED` when a required role, login, credential, network route, workspace registration, or user confirmation is missing. Always state the exact next gate and the remote path affected.

Official references: [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) and [MCPX](https://github.com/opentokenz/mcpx).