🌐 Built for Web Gemini (gemini.google.com), Claude.ai Custom Connectors & ChatGPT MCP — Not Gemini-Only!
Release v0.2.0 GHCR :lite (~300MB) & :full MCP 2025-11-25 Streamable HTTP OAuth 2.1 + PKCE + DCR + Google/GitHub SSO bwrap --unshare-net Sandbox Codex · Claude Code · Gemini CLI · OpenCode

The Universal OAuth 2.1 MCP Bastion for Web Gemini, Claude.ai & ChatGPT

10 Tools · 1 Approval Gate · 1-Min GHCR Deploy · 4 Pluggable Agent Drivers · bwrap FS/Net Jail

Named GeminiBastionMCP because it conquered Web Gemini's strict OAuth 2.1 DCR & 16-redirect-URI requirements first — while speaking 100% standard MCP 2025-11-25 Streamable HTTP for Claude.ai, ChatGPT, and Cursor. Deploy in 1 minute from pre-built GHCR images with bubblewrap per-workspace isolation and pluggable Codex, Claude Code, Gemini CLI, or OpenCode background agents.

ℹ️ This GitHub Pages site is the static documentation & interactive architecture showcase portal (Official MCP Registry ID: io.github.kaiserunix/gemini-bastion-mcp). The live Streamable HTTP /mcp gateway and /admin PWA run self-hosted on your own Docker host or VPS.
Comparison Matrix

Why GeminiBastionMCP Exists

Connecting Web Gemini (gemini.google.com), Claude.ai, or ChatGPT to real repositories and infrastructure usually breaks down on strict OAuth 2.1 DCR handshakes, 40-tool approval popups, or raw secret exposure.

Capability GeminiBastionMCP (v0.2.0) Generic MCP Proxies (MetaMCP) Official Remote MCPs (GitHub/CF) Local Stdio Shell MCPs
Web Gemini, Claude.ai & ChatGPT OAuth 2.1 DCR + SSO ✅ Native for all 3 (RFC 9728/8414/8707, 16 redirect URIs, 8KB state, 60s grace + Google/GitHub SSO) ⚠️ Often lacks RFC 8707 resource binding or 8KB state ✅ Single-vendor only ❌ Desktop stdio only
Web Chat Approval UX ✅ 10 Tools, 1 Approval Gate (Tools 1–9 safe for Always Allow; only #10 writes externally) ❌ Exposes 30–60 granular tools; constant popup fatigue ⚠️ Mixed read/write tools ❌ Confirm every shell call or run unguarded
Pluggable Background Coding Agents & Job Promotion ✅ 4 Drivers (@openai/codex-sdk, Claude Code, Gemini CLI, OpenCode) + 15s auto-job promotion ❌ Router only, no workspace sandbox ❌ REST API wrapper only, cannot run tests ⚠️ Single local shell with no background job promotion
Per-Workspace bwrap Jail & Zero Secret Leakage ✅ bwrap FS/network jail (--unshare-net) + UID 1001/1002 + SecretScrubber + isolated-runner sidecar ❌ Depends on downstream server ✅ Cloud-hosted ❌ Subprocesses inherit host filesystem & secrets
Two-Phase Infrastructure Mutation (Plan → Apply) ✅ stage_mutation_plan (15m TTL + rollback snapshot) → publish_changes ❌ Direct write pass-through ❌ Immediate external writes ❌ None
Pluggable Agent Orchestration (v0.2.0)

4 Background Agent Drivers — 1 Unified dispatch_runner Tool

Switch between OpenAI Codex SDK, Claude Code CLI, Gemini CLI, or OpenCode CLI per job via agent_driver (or set DEFAULT_AGENT_DRIVER). Every write run automatically creates a pre-run GIT_INDEX_FILE snapshot and executes either in-container under UID 1002 or inside a dedicated isolated-runner sidecar container.

⚡ OpenAI Codex SDKcodex (default)

Native @openai/codex-sdk integration supporting thread resumption (resume_thread_id), reasoning_effort, token budgets, and read-only vs workspace-write sandboxes.

🧠 Claude Code CLIclaude_code

Headless Claude Code CLI driver (claude -p --output-format json) with strict read-only tool allowlisting in agent_readonly mode and scoped ANTHROPIC_API_KEY injection.

✨ Gemini CLIgemini_cli

Headless Google Gemini CLI driver (gemini -p) for autonomous repository analysis and multi-file refactoring with scoped GEMINI_API_KEY injection and SecretScrubber protection.

🛠️ OpenCode CLIopencode

OpenCode CLI driver (opencode run) enabling multi-provider open-source coding agent workflows inside the same checkpointed /workspaces/{slug} sandbox.

System Topology v0.2.0

Blast-Radius-Contained Architecture

Stateless Streamable HTTP transport mounted on Hono (/mcp) with UID 1001/1002 separation, bubblewrap per-workspace filesystem & network namespaces, authenticated ops-mcp sidecar proxy, and optional isolated-runner container.

1. Universal AI Clients

Web, Mobile & IDE

gemini.google.com Connected Apps via OAuth 2.1 DCR + PKCE (S256)
Claude.ai & ChatGPT Custom Connectors over Stateless Streamable HTTP (/mcp)
Cursor / Claude Code / CLI Official MCP Registry server.json discovery
2. Control Plane (UID 1001: gateway)

GeminiBastionMCP Core

OAuth 2.1 + Google/GitHub SSO 60s refresh grace + fail-closed upstream OAuth IdP login
SQLite WAL (/data/gateway.db) Mode 0700 owned by UID 1001; inaccessible to worker
SecretScrubber & /admin PWA Redacts tokens across all outputs, logs, artifacts & webhooks
3. Sandbox & Runner (UID 1002 / Sidecar)

bwrap Jail & Multi-Agent

bwrap Per-Workspace Jail Hides other workspaces & blocks network (--unshare-net default)
4 Pluggable Agent Drivers codex · claude_code · gemini_cli · opencode + Git snapshots
Optional isolated-runner Sidecar Dedicated container via AGENT_RUNNER_URL + Bearer auth
4. Single Write Funnel

Audited External Targets

GitHub API (Octokit) Feature-branch PRs, reviews & comments; main/master push blocked
Cloudflare API Read-only inspect vs staged DNS/KV/Workers/Pages mutations
Authenticated ops-mcp (ops_net) Per-request Authorization: Bearer token + tool policy lists
Interactive Contract Explorer

10 Tools, 1 Approval Gate

Filter the 10-tool surface by permission tier. Configure Tools 1–9 as "Always Allow" in Web Gemini, Claude.ai, or ChatGPT for zero-popup autonomous exploration, coding, and staging — keeping Tool #10 (publish_changes) as your single human-in-the-loop approval gate.

Built-In Web Interfaces

Interactive UI Preview: GET / Portal & /admin Cockpit

Toggle between the zero-leakage Public Gateway Portal served at GET / and the mobile-installable Operator Cockpit PWA served at /admin.

Static Interactive Preview (No Live Backend Connected)
GET https://mcp.yourdomain.com/ (Zero Private Data Leakage) CSP: sha256-strict
● ONLINE GeminiBastionMCP v0.2.0
Operator /admin →
Universal MCP Streamable HTTP Endpoint (Web Gemini · Claude.ai · ChatGPT)
✓ /.well-known/oauth-authorization-server · ✓ /.well-known/oauth-protected-resource · ✓ bwrap Sandbox · ✓ 4 Agent Drivers
🟢 workspace_manage 🟢 code_explore 🟢 code_patch 🟢 workspace_exec (bwrap) 🟢 dispatch_runner (4 Drivers) 🟢 job_status 🟢 github_inspect 🟢 infra_inspect 🟡 stage_mutation_plan 🔴 publish_changes (Single Write Gate)
GET https://mcp.yourdomain.com/admin (Authenticated Operator Console PWA) SSE Live Stream ●
Active Jobs
1 ● running
Staged Plans
1 14m TTL
Workspaces
3 bwrap jailed
OAuth Sessions
2 families
acme-api · agent_write (driver: claude_code)
job_9f42c1 · Checkpoint: cp_20261121_01 · Sandbox: bwrap + isolated-runner
RUNNING
Objective: Refactor rate limiter middleware and run L0/L1 vitest suite
---
[12 checkpoint] Created non-destructive GIT_INDEX_FILE snapshot refs/mcp-checkpoints/cp_20261121_01
[13 driver:claude_code] Applied atomic hunk to src/auth/rateLimiter.ts
[14 validate] L0 tsc --noEmit passed (0 errors) | L1 vitest passed
Upstream Operator OAuth SSO Callback URLs
Google: https://mcp.yourdomain.com/auth/idp/google/callback
GitHub: https://mcp.yourdomain.com/auth/idp/github/callback
Defense-in-Depth v2 (v0.2.0)

Per-Workspace bwrap Jail, Bearer Sidecars & Google/GitHub SSO

Engineered so you can safely connect Web Gemini, Claude.ai, and ChatGPT to real GitHub repositories, Cloudflare accounts, and internal infrastructure.

📦 1. Per-Workspace bwrap FS & Network Jail

On Linux/Docker, workspace_exec wraps subprocesses in bubblewrap (bwrap), mounting only /workspaces/{slug} (hiding sibling workspaces) and defaulting to --unshare-net (offline network namespace unless allow_network: true is passed).

🧱 2. Dual-UID Split & isolated-runner Sidecar

gateway runs as UID 1001 owning /data (mode 0700 SQLite WAL DB), while worker runs as UID 1002. Optionally offload all agent drivers to a dedicated isolated-runner container sidecar via AGENT_RUNNER_URL + Bearer token.

🔒 3. Zero Secret Leakage & Authenticated ops-mcp

buildSandboxedEnv() strips all gateway credentials from child processes. Downstream MCP-2 sidecars (ops-mcp) require per-request Authorization: Bearer tokens (OPS_MCP_AUTH_TOKEN) and fail closed if misconfigured.

⏪ 4. Non-Destructive GIT_INDEX_FILE Snapshots

Before every code_patch, codex_write, or agent_write run, the gateway snapshots tracked and untracked files into refs/mcp-checkpoints/* using a temporary GIT_INDEX_FILE without touching your real .git/index or HEAD.

🚦 5. Main-Branch Block & Two-Phase Mutations

Direct pushes to main, master, or default_branch are physically rejected. Cloudflare and downstream MCP-2 mutations must be staged via stage_mutation_plan (15m TTL + rollback payload) before publish_changes executes them.

🔑 6. OAuth 2.1 Family Rotation & Google/GitHub SSO

Supports PKCE (S256), RFC 8707 Resource Indicators, 60s refresh token family rotation, untrusted prompt-injection boundaries, plus fail-closed Google & GitHub OAuth operator login.

Zero-Build GHCR Deployment (v0.2.0)

1-Minute Quick Start (:lite & :full Images)

Pull pre-built multi-arch images directly from GitHub Container Registry (choose :lite ~300MB for fast Node/TS/Git + bwrap, or :full with Python/uv/ripgrep/ast-grep/Codex/Claude Code/Gemini CLI/OpenCode), then paste your /mcp endpoint into Web Gemini, Claude.ai, or ChatGPT.

1. Pull Pre-Built GHCR Image (:lite ~300MB or :full) & Generate Secrets

# Option A: Lightweight image (~300MB, Node 22 + Git + bubblewrap)
docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:lite

# Option B: Full Polyglot + Multi-Agent CLI image (includes Python/uv, ripgrep, ast-grep, Codex/Claude/Gemini/OpenCode CLIs)
docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:full

# Generate ADMIN_PASSWORD_HASH (scrypt::) & OAUTH_SIGNING_SECRET:
node -e 'const c=require("node:crypto"),s=c.randomBytes(16).toString("hex");console.log(`ADMIN_PASSWORD_HASH=scrypt:${s}:${c.scryptSync(process.argv[1],s,32,{N:16384,r:8,p:1}).toString("hex")}`)' 'your-strong-operator-password'
node -e 'console.log("OAUTH_SIGNING_SECRET=" + require("node:crypto").randomBytes(32).toString("hex"))'

2. Launch Docker Compose Stack (Optional --profile ops or --profile isolated-runner)

git clone https://github.com/Kaiserunix/gemini-bastion-mcp.git
cd gemini-bastion-mcp
cp .env.example .env
# Edit .env: set PUBLIC_DOMAIN, ADMIN_PASSWORD_HASH, OAUTH_SIGNING_SECRET, DEFAULT_AGENT_DRIVER=codex
# Start core stack (or add --profile ops --profile isolated-runner):
docker compose -f docker/docker-compose.yml up -d

3. Connect Web Gemini (gemini.google.com), Claude.ai & ChatGPT

# Universal MCP Streamable HTTP Endpoint (OAuth 2.1 DCR auto-discovers /.well-known/*):
https://mcp.yourdomain.com/mcp

# Recommended Client Tool Permission Policy:
# - Tools 1..9 (workspace_manage .. stage_mutation_plan) -> Always Allow (0 popups)
# - Tool 10 (publish_changes)                            -> Ask Before Running (Single Write Gate)