# Connect ChatGPT-Computer-MCP to ChatGPT

This project is designed for a private local MCP path:

```text
ChatGPT Developer Mode
        |
OpenAI Secure MCP Tunnel
        |
        | outbound HTTPS
        v
tunnel-client on Linux
        |
        | stdio
        v
ChatGPT-Computer-MCP
```

The MCP server itself does not need a public listener.

Official references:

- https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
- https://developers.openai.com/api/docs/guides/developer-mode
- https://github.com/openai/tunnel-client

## 1. Create the tunnel

Open Platform tunnel settings:

https://platform.openai.com/settings/organization/tunnels

Create a tunnel and retain its `tunnel_id`. The example shape is:

```text
tunnel_0123456789abcdef0123456789abcdef
```

Make sure the tunnel is associated with the ChatGPT workspace/account that should use **ChatGPT-Computer-MCP**.

OpenAI currently separates permissions:

- create/edit tunnel: **Tunnels Read + Manage**;
- run `tunnel-client` or choose the tunnel while creating an app: **Tunnels Read + Use**.

## 2. Create a runtime API key

Create a normal runtime key for `tunnel-client` in Platform. The key authenticates the tunnel client to the OpenAI tunnel control plane; this MCP does not use it to call a model API.

The installer stores the key only in:

```text
.secrets/runtime-api-key
```

with restrictive local permissions. Never commit it.

## 3. Automated local setup

From the repository root:

```sh
./install.sh
```

Or non-interactively:

```sh
export CONTROL_PLANE_TUNNEL_ID='tunnel_0123456789abcdef0123456789abcdef'
export CONTROL_PLANE_API_KEY='sk-...'
./install.sh --yes
```

The installer:

- verifies Linux + Node.js 22+;
- installs dependencies with the project-pinned pnpm 11.20.0;
- runs the complete project gate;
- copies `config.example.json` to local-only `config.local.json` when needed;
- checks/installs X11 dependencies and Wayland native build/runtime dependencies;
- obtains the latest official `tunnel-client` when it is missing;
- initializes a `chatgpt-computer-mcp` tunnel profile;
- runs `tunnel-client doctor --explain`;
- creates and starts a systemd user service.

## 4. Manual tunnel setup

Build first:

```sh
pnpm install
pnpm gate
cp config.example.json config.local.json
```

Set the config path:

```sh
export CHATGPT_COMPUTER_MCP_CONFIG="$PWD/config.local.json"
```

Initialize a stdio profile:

```sh
export CONTROL_PLANE_API_KEY='sk-...'

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile chatgpt-computer-mcp \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "node /ABSOLUTE/PATH/chatgpt-computer-mcp/dist/src/stdio.js"
```

Validate and run it:

```sh
tunnel-client doctor --profile chatgpt-computer-mcp --explain
tunnel-client run --profile chatgpt-computer-mcp
```

Keep `tunnel-client` healthy while testing ChatGPT; discovery and tool calls depend on the running tunnel client.

## 5. Create the ChatGPT app

Use the app name:

**ChatGPT-Computer-MCP**

On ChatGPT web:

1. Open **Settings → Security and login** and enable **Developer mode**.
2. Open https://chatgpt.com/plugins .
3. Select the plus button and create a developer-mode app.
4. Under **Connection**, choose **Tunnel**.
5. Select the available tunnel or paste the `tunnel_id` when offered.
6. Enable **ChatGPT-Computer-MCP** in the conversation.

If the tunnel is absent, verify its ChatGPT workspace association and the operator's **Tunnels Read + Use** permission.

## 6. First test

Start read-only:

```text
Use ChatGPT-Computer-MCP computer.info and report the displays and coordinate spaces.
```

Then observe:

```text
Use ChatGPT-Computer-MCP computer.observe to capture the desktop. Do not take any action.
```

Then try a harmless explicit action only after confirming the coordinates:

```text
Use ChatGPT-Computer-MCP computer.act to move the pointer to the specified desktop coordinate. Do not click.
```

The MCP never observes after an action unless ChatGPT makes another `computer.observe` call.

## 7. Operations

```sh
./scripts/status.sh
./scripts/doctor.sh
```

Remove only the persistent tunnel service/profile while leaving local config and secrets untouched:

```sh
./scripts/uninstall.sh
```

## Troubleshooting

### `computer.info` fails

Check:

```sh
./scripts/doctor.sh
```

For X11, `DISPLAY`, X authorization, `xrandr`, FFmpeg, and `xdotool` must be usable by the process running the MCP.

### Wayland session detected

`backend: "auto"` selects the native Wayland backend. The first `computer.info`/observe/action that initializes it can open the desktop portal monitor/device consent UI. Allow the intended monitors and pointer/keyboard control.

If initialization fails, run `./scripts/doctor.sh`. It checks the user D-Bus portal, the native helper, and runtime libraries. See [`WAYLAND.md`](./WAYLAND.md) for the portal/PipeWire/libei requirements and coordinate model.

### Tunnel is not visible

Confirm:

- the tunnel includes the target ChatGPT workspace;
- the account has Tunnels Read + Use;
- `tunnel-client` is running and healthy;
- `tunnel-client doctor --profile chatgpt-computer-mcp --explain` passes.