openchatx-mcp

How it works — official MCP, no reverse engineering

OpenChatX uses OpenAI's documented MCP integration path. It does not reverse-engineer ChatGPT, call undocumented ChatGPT backend endpoints, reuse browser session cookies, or intercept ChatGPT traffic.

The connection works like this:

1. OpenChatX runs a normal MCP server locally on your machine.

2. OpenAI's official tunnel-client creates an outbound HTTPS connection to an OpenAI Secure MCP Tunnel. Your local MCP server does not need a public inbound port.

3. ChatGPT connects to that tunnel as a custom MCP app using the supported ChatGPT Developer Mode / MCP app flow.

4. When ChatGPT invokes a tool, the Secure MCP Tunnel forwards the MCP request to OpenChatX locally and returns the MCP response through the same official channel.

5. OpenChatX then routes that request to local tools, your computer, connected MCP servers, Skills, Rules, Projects, or explicitly configured Subagents.

ChatGPT remains the model and planner. OpenChatX is the local tool/runtime layer; it does not impersonate ChatGPT or make hidden model calls on ChatGPT's behalf.

The Runtime API key configured in OpenChatX is used for the official Secure MCP Tunnel control plane and is stored in the operating-system credential store. It is not a scraped ChatGPT credential or a workaround around ChatGPT's supported interfaces.

Official references:

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

• ChatGPT Developer Mode and MCP apps: https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt

Related MCP server: Codex 2.0 MCP Gateway

Install the Desktop App

This is the recommended way to use OpenChatX. You do not need to install Node.js, npm, PM2, or tunnel-client yourself.

macOS

Download the matching DMG from the latest release:

• Apple Silicon: OpenChatX-macos-arm64.dmg

• Intel Mac: OpenChatX-macos-x64.dmg

The macOS release is signed with Developer ID and notarized by Apple.

Windows

For most PCs, download:

• OpenChatX-Setup-x64.exe

For Windows on ARM:

• OpenChatX-Setup-arm64.exe

Portable ZIPs are also available.

Latest release:

https://github.com/XiaoPuOuO/openchatx-mcp/releases/latest

Connect OpenChatX to ChatGPT

OpenChatX uses OpenAI Secure MCP Tunnel. The Desktop App manages the local runtime and bundled tunnel-client; you only need to create the tunnel once.

1. Create the ChatGPT MCP app

Open ChatGPT Settings and enable Developer Mode.

Then open Plugins, click +, choose Create app, and then choose Create MCP app.

Enter the app name and description, switch the connection type to Tunnel, and click Create tunnel.

2. Create the tunnel in OpenAI Platform

Open the OpenAI Platform Tunnels page:

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

Click Create tunnel, then configure:

1. Name — for example, OpenChatX Tunnel.

2. Description — for example, OpenChatX Tunnel.

3. Organizations — select the organization that should own the tunnel.

4. ChatGPT workspaces — select the ChatGPT workspace that will use OpenChatX.

5. Click Create.

After creation, copy the resulting tunnel_... ID. You will enter this in OpenChatX Desktop.

3. Create the Runtime API key

Open the OpenAI Platform API Keys page:

https://platform.openai.com/settings/organization/api-keys

Create a new secret key for the OpenChatX tunnel runtime. A name such as OpenChatX Runtime Key makes it easier to identify later.

Copy the secret when it is shown. Do not commit it to Git or paste it into chat.

4. Connect the Desktop App

Open OpenChatX Desktop → More → Connect Tunnel…

Enter:

• Tunnel ID — the tunnel_... ID from step 2.

• Control-plane API key — the Runtime API key from step 3.

The Desktop App stores the API key in the operating-system credential store:

• macOS: Keychain

• Windows: Credential Manager

5. Finish the ChatGPT MCP app

Return to ChatGPT:

1. Select the newly created openchatx (tunnel_...) tunnel.

2. Set authentication to No authentication.

3. Read and accept the custom MCP risk acknowledgement.

4. Click Create.

If you want ChatGPT to use OpenChatX tools without prompting for every tool call, you can set the OpenChatX app permission to Allow all tools.

Useful links:

• OpenAI Secure MCP Tunnel guide: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

• OpenAI Tunnels settings: https://platform.openai.com/settings/organization/tunnels

• OpenAI API keys: https://platform.openai.com/settings/organization/api-keys

What OpenChatX gives ChatGPT

External MCP and Toolbox schemas stay lazy so the normal ChatGPT tool context stays small.

Skills, Rules, and AGENTS.md

Skills

Skills are portable Agent Skills owned by a Toolbox:

toolboxes/<toolbox>/skills/<name>/SKILL.md

A Skill contains name, description, and Markdown instructions. Skills are not injected at startup.

• skill_search finds up to five relevant Skills by name/description.

• skill_load loads the full Markdown only after a Skill is selected.

• skill_manage creates, edits, or deletes user Skills.

Rules

Rules are owned by a Toolbox and live beside that Toolbox's other capabilities:

toolboxes/<toolbox>/rules/<name>.mdc

Example:

---
description: "React component conventions"
globs:
  - "src/**/*.tsx"
alwaysApply: false
---

Use accessible labels and named exports.

OpenChatX supports four Rule modes:

• Always — injected by start_here.

• Auto Attached — activated by matching file globs.

• Agent Requested — selected from the description when relevant.

• Manual — loaded only when explicitly requested.

Rules can be imported/exported with Cursor .mdc, Claude Rules, and AGENTS.md.

AGENTS.md

~/.openchatx-mcp/AGENTS.md is the editable template used by start_here.

The Toolbox UI exposes it directly. Runtime data is inserted through placeholders such as:

• {{MODE_INSTRUCTIONS}}

• {{PROJECT_CONTEXT}}

• {{CAPABILITY_CATALOG}}

• {{ALWAYS_RULES}}

Move or remove placeholders to control what start_here returns.

Connect more capabilities

You can usually just ask ChatGPT:

Add this MCP server to OpenChatX and verify it works.

or:

Create an OpenChatX tool that starts my local service and returns its status.

OpenChatX can manage MCP servers, Toolboxes, Skills, Rules, Projects, and Subagents from the Dashboard or through its management tools.

Manual / source install

Use this only if you do not want the Desktop App.

Requirements

• Node.js 22.18+

• npm

• ripgrep

• OpenAI tunnel-client

• ChatGPT Developer Mode / custom MCP access

macOS

brew install ripgrep
git clone https://github.com/XiaoPuOuO/openchatx-mcp.git
cd openchatx-mcp
npm ci
npm run setup -- --config-only

Windows PowerShell

winget install BurntSushi.ripgrep.MSVC
git clone https://github.com/XiaoPuOuO/openchatx-mcp.git
Set-Location openchatx-mcp
npm ci
npm run setup -- --config-only

Then install the official OpenAI tunnel-client, create the openchatx tunnel profile, export CONTROL_PLANE_API_KEY, and run:

npm run setup
npm start

Useful commands:

Development

npm ci
npm --prefix ui ci
npm run lint
npm run typecheck
npm test
npm run build
npm --prefix ui run build

Desktop build commands:

npm run desktop:build
npm run desktop:smoke
npm run desktop:windows:build
npm run desktop:windows:build:arm64

Maintainer docs: wiki/

Security

• Only connect MCP servers you trust.

• The local MCP endpoint is intended to stay on loopback.

• Secure MCP Tunnel is the supported remote path.

• Tool/audit logs may contain sensitive inputs.

• See SECURITY.md for the security model and reporting instructions.

License

MIT — see LICENSE.

Parts of this project are derived from Shellby MCP; see THIRD_PARTY_NOTICES.md.