OpenCode MCP Gateway Cloudflare Desktop

[!WARNING] This project exposes remote shell execution, PTY control, session steering, and agent-driven code execution on the machine where it runs. Treat it like a personal-use remote code execution service. If this gateway is compromised, an attacker may be able to read files, execute commands, access credentials, damage data, or pivot deeper into your environment. Do not expose it to untrusted users. Use strong secrets. Keep the origin machine locked down.

This repository is the Cloudflare desktop deployment variant of opencode-mcp-gateway.

It is designed for:

• an Ubuntu desktop or laptop
• a local OpenCode server
• a public HTTPS MCP endpoint fronted by Cloudflare Tunnel
• Claude and ChatGPT OAuth-compatible remote MCP usage
• no VPS

Repository:

• https://github.com/gjabdelnoor/opencode-mcp-gateway-cloudflare-desktop

Architecture

Claude / ChatGPT
        |
        v
  https://mcp.example.com/mcp
        |
        v
   Cloudflare Edge
        |
        v
   cloudflared tunnel
        |
        v
  http://127.0.0.1:3001
        |
        v
  http://127.0.0.1:9999
        |
        v
      OpenCode

Read This First

You need OpenCode installed and working before this gateway can do anything useful.

OpenCode docs:

• Intro: https://opencode.ai/docs/
• Providers: https://opencode.ai/docs/providers/
• Server mode: https://opencode.ai/docs/server/

Detailed docs in this repo:

• docs/ubuntu-cloudflare-desktop-setup.md
• docs/session-change-map.md

Installation Paths

There are two practical install paths documented here.

Path A: Purchased Domain + Cloudflare DNS

This is the recommended path.

Use this when you want a stable hostname like:

• https://mcp.example.com/mcp

Why this is better:

• stable OAuth issuer URL
• stable connector configuration
• better long-term reliability
• easier to run multiple gateways like mcp1, mcp2, mcp3

Path B: Free Cloudflare trycloudflare Tunnel

This is the free, no-personal-domain path.

Use this when you want to experiment without buying or wiring a domain.

Why this is worse:

• hostname is temporary
• hostname can change on reconnect
• OAuth clients may break when the issuer URL changes
• not ideal for durable Claude or ChatGPT connectors

Quick Start

1. Install Ubuntu packages

sudo apt update
sudo apt install -y curl git python3 python3-pip python3-venv

2. Install and configure OpenCode

curl -fsSL https://opencode.ai/install | bash

Then configure a provider and start OpenCode locally:

opencode serve --hostname 127.0.0.1 --port 9999

3. Clone this repo and install dependencies

git clone https://github.com/gjabdelnoor/opencode-mcp-gateway-cloudflare-desktop.git
cd opencode-mcp-gateway-cloudflare-desktop
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. Create .env

cp .env.example .env

Example:

MCP_AUTH_TOKEN=replace-with-a-long-random-secret
MCP_CLIENT_ID=opencode-mcp-gateway
MCP_ALLOWED_CLIENT_IDS=opencode-mcp-gateway
PUBLIC_BASE_URL=https://mcp.example.com
DEFAULT_WORKSPACE_DIR="/home/YOUR_USER/AI Projects"
OPENCODE_HOST=127.0.0.1
OPENCODE_PORT=9999
GATEWAY_PORT=3001
ENABLE_RAW_BASH=true
DEFAULT_PLANNING_MODEL=opencode/minimax-m2.5-free
DEFAULT_BUILDING_MODEL=openai/gpt-5.4-mini

5. Choose a tunnel path

Purchased domain path

Install cloudflared:

curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
rm cloudflared.deb

Authenticate and create the tunnel:

cloudflared tunnel login
cloudflared tunnel create opencode-mcp-gateway
cloudflared tunnel route dns opencode-mcp-gateway mcp.example.com

Create ~/.cloudflared/config.yml:

tunnel: YOUR_TUNNEL_ID
credentials-file: /home/YOUR_USER/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: mcp.example.com
    service: http://127.0.0.1:3001
    originRequest:
      httpHostHeader: mcp.example.com
  - service: http_status:404

Set:

• PUBLIC_BASE_URL=https://mcp.example.com

Run the tunnel:

cloudflared tunnel run opencode-mcp-gateway

Free trycloudflare path

Install cloudflared the same way, then run:

cloudflared tunnel --url http://127.0.0.1:3001

That gives you a temporary https://...trycloudflare.com URL.

Use that URL as:

• PUBLIC_BASE_URL=https://YOUR-TEMP-HOST.trycloudflare.com

Important caveat:

• this path is still considered experimental here
• if the hostname changes, you will usually need to recreate the connector in Claude or ChatGPT

6. Start the gateway

source .venv/bin/activate
python main.py

Verify The Deployment

Check:

curl https://mcp.example.com/.well-known/oauth-authorization-server
curl https://mcp.example.com/.well-known/oauth-authorization-server/mcp
curl https://mcp.example.com/.well-known/oauth-protected-resource
curl -D - -o /dev/null https://mcp.example.com/mcp

You want:

• OAuth issuer: https://mcp.example.com
• token endpoint: https://mcp.example.com/oauth/token
• protected resource: https://mcp.example.com/mcp
• unauthorized /mcp returns 401 with WWW-Authenticate and resource_metadata

Connect ChatGPT Or Claude

MCP server URL:

https://mcp.example.com/mcp

OAuth discovery URLs:

• Claude: https://mcp.example.com/.well-known/oauth-authorization-server
• ChatGPT: https://mcp.example.com/.well-known/oauth-authorization-server/mcp

Manual OAuth values when needed:

• OAuth Client ID: opencode-mcp-gateway
• OAuth Client Secret: your MCP_AUTH_TOKEN
• Token auth method: client_secret_post
• Scope: mcp

Multiple Concurrent Agents

If you want multiple chatbot-controlled agents at once, run multiple gateway processes.

Recommended layout:

• mcp1.example.com -> localhost:3001
• mcp2.example.com -> localhost:3002
• mcp3.example.com -> localhost:3003
• mcp4.example.com -> localhost:3004
• mcp5.example.com -> localhost:3005
• mcp6.example.com -> localhost:3006

Each instance should have its own:

• PUBLIC_BASE_URL
• GATEWAY_PORT
• MCP_AUTH_TOKEN
• MCP_CLIENT_ID

Configuration

Variable	Description
MCP_AUTH_TOKEN	Bearer secret for OAuth token exchange and MCP access
MCP_CLIENT_ID	Main OAuth client ID accepted by the gateway
MCP_ALLOWED_CLIENT_IDS	Optional comma-separated allowlist of additional client IDs
PUBLIC_BASE_URL	External HTTPS base URL advertised in OAuth metadata
DEFAULT_WORKSPACE_DIR	Default project root for new sessions and PTYs
OPENCODE_HOST	OpenCode origin host
OPENCODE_PORT	OpenCode origin port
GATEWAY_PORT	Gateway listen port
ENABLE_RAW_BASH	Enables direct bash and bash_exec tools
DEFAULT_PLANNING_MODEL	Optional fallback model for planning-mode sessions
DEFAULT_BUILDING_MODEL	Optional fallback model for building-mode sessions
BLOCKED_SESSION_MODELS	Optional comma-separated models to reject even if OpenCode advertises them

Troubleshooting

ChatGPT says the server URL is invalid

Use the full MCP URL:

https://mcp.example.com/mcp

Claude reaches login but the connector still fails

Check:

• PUBLIC_BASE_URL is correct
• protected resource metadata returns https://mcp.example.com/mcp
• GET /mcp without auth returns 401 with WWW-Authenticate
• the OAuth client secret exactly matches MCP_AUTH_TOKEN

session_create or send_message looks stalled

Check:

curl http://127.0.0.1:9999/session/status

If OpenCode is retrying an unsupported model, set or adjust:

DEFAULT_PLANNING_MODEL=opencode/minimax-m2.5-free
DEFAULT_BUILDING_MODEL=openai/gpt-5.4-mini

switch_model rejects a model you thought should work

The gateway now validates against OpenCode’s live model catalog.

It will reject:

• anything not currently exposed by OpenCode
• I may have hardcoded it to reject the two known-bad models on my minimax plan... oops:
  • minimax-coding-plan/MiniMax-M2.5-highspeed
  • minimax-coding-plan/MiniMax-M2.7-highspeed

Sessions are starting in the wrong folder

Set:

DEFAULT_WORKSPACE_DIR="/home/YOUR_USER/AI Projects"

This repo now defaults new sessions and PTYs to that workspace if you do not pass an explicit directory.

Several bots interfere with each other

Use separate gateway instances on separate hostnames and ports.

Full Docs

• docs/ubuntu-cloudflare-desktop-setup.md
• docs/session-change-map.md

Questions Or Security Concerns

If you have questions, comments, setup issues, or serious security concerns, contact @isnotgabe on Discord.