GeminiBastionMCP
Provides read-only inspection of Cloudflare zones, DNS records, Workers, Pages, KV namespaces, D1 databases, WAF rules, and Worker tail logs; supports staged mutation plans with rollback snapshots and approval-gated Worker/Pages deployments.
Enables repository syncing and read-only inspection of pull request diffs/files, issue threads, and failed Actions logs; publishes changes through pull requests, reviews, and comments while blocking direct pushes to main/master.
Dispatches background OpenAI Codex autonomous coding threads in read-only or write mode, with thread resume and token/duration budgets.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
GeminiBastionMCP (gemini-bastion-mcp)
English | 简体中文 | Live Showcase Site | GitHub Repo
The self-hosted OAuth 2.1 MCP bastion that turns Web Gemini, Claude & ChatGPT into a sandboxed full-stack coding, Codex & Cloudflare ops agent — with 10 tools and 1 approval gate.
Code from
gemini.google.comon Mobile or Desktop: Open Web Gemini, sync a GitHub repository, inspect AST/files withripgrep,ast-grep, andrepomix, apply multi-file atomic patches, and run L0/L1/L2 validation suites — without touching a laptop.Delegate Heavy Work to Background Codex & Shell Jobs: Dispatch
@openai/codex-sdkautonomous threads or long builds (workspace_execauto-promotes to background SQLite jobs after 15s). Close the browser tab and receive a scrubbed Webhook alert when it finishes.Zero Secret Leakage & 1-Gate Blast Radius: Sandboxed child processes never see
GH_TOKEN,CLOUDFLARE_*, or gateway secrets. Non-destructiveGIT_INDEX_FILEcheckpoints protect your working tree, direct pushes tomain/masterare blocked, and every external side effect is funneled through one single approval gate (publish_changes).
Built for Web Gemini Connected Apps, Claude.ai, ChatGPT Connectors, Cursor & MCP Inspector.
Why This Exists
Most remote MCP setups force an unpleasant tradeoff: either expose dozens of granular tools (triggering endless approval popups on every file read or test run) or run an unguarded shell directly on your host.
Capability | GeminiBastionMCP | Generic Aggregators (e.g. MetaMCP) | Official Remote MCPs (GitHub / CF) | Local Shell / Stdio MCP |
Web Gemini ( | Full Support (OAuth 2.1 + PKCE S256 + DCR up to 16 redirect URIs + 8KB | Often missing RFC 9728/8707 or large | Single-vendor hosted only | Desktop/local client only |
Web Chat Approval UX | 10 Tools, 1 Approval Gate (Tier 1/2 | Dozens of fragmented tools = constant confirmation popups | Read & write tools mixed | Confirm every shell command or run wide open |
Sandboxed Test Runner + Async Codex | Built-in ( | No execution sandbox | API-only; cannot run local builds/tests | Runs on host; no background job promotion |
Secret Isolation & Undo | Dual-UID (1001/1002) + Env Allowlist + | Depends on downstream servers | Cloud-managed | Child processes inherit host env |
Two-Phase Infra Mutations |
| Direct passthrough writes | Direct writes | None |
Related MCP server: Codebase MCP Bridge
Architecture Overview
flowchart LR
subgraph Clients["Web & Mobile AI Clients"]
G["gemini.google.com\n(Connected Apps)"]
C["Claude.ai / ChatGPT\n/ Cursor / Inspector"]
end
subgraph Edge["Zero-Port Edge Ingress"]
CF["Cloudflare Tunnel\nor TLS Nginx Proxy"]
end
subgraph Gateway["GeminiBastionMCP Gateway (UID 1001: gateway)"]
Portal["GET / Public Portal\n(Zero Private Data)"]
Auth["OAuth 2.1 + PKCE + DCR\nRFC 8707/9728 + Family Rotation"]
Scrub["SecretScrubber &\nUntrusted Boundary"]
Admin["/admin Mobile PWA\nSSE Live Jobs & Rollback"]
DB[("SQLite WAL (/data)\n0700 gateway-only")]
subgraph Funnel["10-Tool Contract (1 Approval Gate)"]
T1_8["Tier 1 (1-8): Sandbox & Read-Only\nworkspace_manage · code_explore · code_patch\nworkspace_exec · dispatch_runner · job_status\ngithub_inspect · infra_inspect"]
T9["Tier 2 (9): Two-Phase Stage\nstage_mutation_plan (15m TTL + Snapshot)"]
T10["Tier 3 (10): Single External Write Gate\npublish_changes (PR / CF Deploy / Execute Plan)"]
end
end
subgraph Sandbox["Isolated Worker Sandbox (UID 1002: worker)"]
WS["/workspaces/{slug}\nGIT_INDEX_FILE Checkpoints\nL0/L1/L2 Validation"]
Codex["@openai/codex-sdk &\nSandboxed Shell (0 Secrets)"]
end
subgraph External["External Targets & Internal ops_net"]
GH["GitHub API\n(No push to main/master)"]
CFApi["Cloudflare API\n(Workers / Pages / DNS / KV)"]
MCP2["Downstream MCP-2 Sidecars\n(e.g. ops-ssh on ops_net)"]
end
Clients -->|"Streamable HTTP /mcp"| CF --> Auth --> Funnel
CF --> Portal & Admin
T1_8 --> WS & Codex
T1_8 -.->|"Read-Only"| GH & CFApi & MCP2
T9 -->|"Stage Plan + Rollback Snapshot"| DB
T10 -->|"Audited & Scrubbed Writes"| GH & CFApi & MCP2
Admin --> DB & WS10 Tools, 1 Approval Gate
Instead of exposing 40+ fine-grained tools that bury mobile/web users under approval prompts, GeminiBastionMCP groups every capability by blast radius so you can configure permissions cleanly in Web Gemini / Claude:
Tier 1 — Sandbox Autonomy & Read-Only Inspection (Set to Always Allow)
# | Tool | Actions & Behavior |
1 |
|
|
2 |
|
|
3 |
| Atomic multi-file |
4 |
| Sandboxed shell in |
5 |
| Background |
6 |
| Poll job status, streamed events, token usage, |
7 |
| Read-only PR diffs/files, issue threads, and failed Actions logs (wrapped with untrusted-data boundary markers) |
8 |
| Read-only Cloudflare inspection ( |
Tier 2 — Zero-Side-Effect Change Staging (Set to Always Allow)
# | Tool | Actions & Behavior |
9 |
| Captures pre-change live state to build a |
Tier 3 — Single External Write Gate (Set to Ask Before Running)
# | Tool | Actions & Behavior |
10 |
| The ONLY external write exit: |
3-Minute Quick Start
Option A: Docker Compose + Cloudflare Tunnel (Recommended)
docker/docker-compose.yml runs gateway with zero host ports exposed (expose: ["8787"] only). All external HTTPS traffic enters through cloudflared.
Create
.envfrom the template:cp .env.example .envGenerate your
ADMIN_PASSWORD_HASH(scrypt:) andOAUTH_SIGNING_SECRET: Supported formats forADMIN_PASSWORD_HASHin production arescrypt:<saltHex>:<keyHex>(recommended, Docker-Compose-safe without$escaping) andsha256:<hex>(legacyscrypt$<saltHex>$<keyHex>andsha256$<hex>are also supported; escape$as$$if used in Docker Compose.env). Generate ascrypt:hash with Node 22:node -e 'const c=require("node:crypto"),s=c.randomBytes(16).toString("hex");console.log(`scrypt:${s}:${c.scryptSync(process.argv[1],s,32,{N:16384,r:8,p:1}).toString("hex")}`)' 'your-admin-password'Generate a 32-byte
OAUTH_SIGNING_SECRET:node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))'Configure required
.envvalues:PUBLIC_DOMAIN=https://mcp.yourdomain.comTRUST_CF_CONNECTING_IP=trueOAUTH_SIGNING_SECRET=<generated hex>ADMIN_PASSWORD_HASH=<generated scrypt:...>CLOUDFLARE_TUNNEL_TOKEN=<your Cloudflare Zero Trust tunnel token>Integration credentials as needed:
GH_TOKEN,OPENAI_API_KEY/CODEX_API_KEY,CLOUDFLARE_ACCOUNT_ID,CLOUDFLARE_READONLY_API_TOKEN,CLOUDFLARE_API_TOKEN
Point your Cloudflare Tunnel Public Hostname (Zero Trust -> Networks -> Tunnels) for
mcp.yourdomain.comtohttp://gateway:8787, and placeCLOUDFLARE_TUNNEL_TOKEN=<token>indocker/.env(or export it in your shell).Build & launch:
docker compose -f docker/docker-compose.yml up -d --buildNote on Docker Compose
.envescaping: Usingscrypt:<saltHex>:<keyHex>avoids Compose$varinterpolation completely. If you use legacyscrypt$...in.envwith Docker Compose, escape every$as$$. Node 22 Security Baseline:docker/DockerfileverifiesNode >= 22.23.4at build time. Override the base tag anytime withNODE_IMAGE=node:22.23.4-bookworm-slim(or newer) indocker/.envor--build-arg. Note thatcloudflaredreceives onlyTUNNEL_TOKEN(never mounts../.env).
Option B: Reverse Proxy with Nginx (Loopback Host Port)
If you already terminate TLS with Nginx on a VPS instead of Cloudflare Tunnel:
Bind
gatewaystrictly to loopback (127.0.0.1:8787:8787or127.0.0.1:39120:8787) via adocker-compose.override.yml, setTRUST_CF_CONNECTING_IP=falsein.env(unless fronted by Cloudflare), and rungatewaywithoutcloudflared:docker compose -f docker/docker-compose.yml up -d --build gatewayProxy HTTPS traffic to the loopback port with buffering disabled for Streamable HTTP &
/adminSSE:location / { proxy_pass http://127.0.0.1:8787; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_read_timeout 300s; }
Option C: Local Development
Prerequisites: Node.js >= 22.23.4, git, and C++ build tools for better-sqlite3.
npm install
cp .env.example .env
# Set DATA_DIR=./.local/data, WORKSPACES_DIR=./.local/workspaces, OAUTH_SIGNING_SECRET, and ADMIN_PASSWORD_HASH
npm run typecheck
npm test
npm run devVerify at http://127.0.0.1:8787/healthz and http://127.0.0.1:8787/. Both npm run dev and npm start automatically load .env via Node's --env-file-if-exists=.env.
Connecting AI Clients
GeminiBastionMCP implements MCP 2025-11-25 Streamable HTTP (stateless /mcp, no legacy HTTP+SSE) with OAuth 2.1 + PKCE (S256) + RFC 8707 Resource Indicators + RFC 9728 Protected Resource Metadata.
Web Gemini (gemini.google.com Connected Apps)
Confirm
PUBLIC_DOMAINmatches your public HTTPS URL andOAUTH_ALLOWED_REDIRECT_HOSTSincludesgemini.google.com,aistudio.google.com,accounts.google.com(default in.env.example).In Gemini Connected Apps / Custom MCP connector settings, enter:
https://mcp.yourdomain.com/mcpGemini automatically discovers
/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server, and registers viaPOST /oauth/register(supports up to 16 redirect URIs per client andstatevalues up to 8192 bytes).Complete the browser OAuth consent prompt. Refresh tokens rotate with a 60-second grace window for concurrent retries.
Claude.ai, ChatGPT & MCP Inspector (DCR or Static Client Fallback)
Automatic DCR: Point Claude.ai Custom Connectors, ChatGPT, or MCP Inspector directly to
https://mcp.yourdomain.com/mcp.Static Client Fallback: If a client requires pre-configured credentials, set
OAUTH_STATIC_CLIENT_IDandOAUTH_STATIC_CLIENT_SECRETin.env, restartgateway, and configure:MCP URL:
https://mcp.yourdomain.com/mcpAuthorization URL:
https://mcp.yourdomain.com/oauth/authorizeToken URL:
https://mcp.yourdomain.com/oauth/token
Public Gateway Portal (GET /) & /admin Mobile PWA
Public Gateway Portal (
GET /): Returns a clean dark-mode status page with one-click/mcpendpoint copy,.well-knowndiscovery links, quick-connect instructions, and a link to/admin— without querying or exposing any private workspaces, jobs, tokens, or secrets. Clients requestingAccept: application/jsonreceive structured JSON status metadata.Operator Command Cockpit (
/admin): Sign in with the password matchingADMIN_PASSWORD_HASH. The mobile-installable PWA provides a top 4-KPI Pulse Strip (Active Jobs,Staged Plans,Workspaces,OAuth Sessions), one-click/mcpURL copy, live SSE job logs with[Expand / Collapse], confirmation prompts on destructive actions (Kill,Rollback,Revoke,Delete Client), and scrubbedaudit_logs.
6-Layer Security & Guardrails
Zero Secret Leakage:
workspace_exec,shell_task, and Codex runners usebuildSandboxedEnv()(strict allowlist strippingGH_TOKEN,CLOUDFLARE_*,OAUTH_SIGNING_SECRET,ADMIN_PASSWORD_HASH,NOTIFY_WEBHOOK_URL, andDOWNSTREAM_MCPS_*). All outputs, artifacts, and webhooks pass throughSecretScrubber.Linux UID 1001 / 1002 Isolation: In Docker,
gateway(UID1001) owns/data(0700, SQLite DB,/data/artifacts, andCODEX_HOME=/data/codex) and/app, whileworker(UID1002) owns/workspacesand/opt/misewith zero access to/data(and/opt/mise/shimsis excluded fromgateway'sPATH).Non-Destructive Git Checkpoints: Pre-patch and pre-Codex snapshots use a temporary
GIT_INDEX_FILE(refs/mcp-checkpoints/*) without mutating your working tree index orHEAD.Protected Branch & Diff Guard:
publish_changes(github_pr) blocks direct pushes tomain,master, or the repo's default branch, and blocks committing sensitive files (.env*,*.pem,*.key,id_rsa*,.dev.vars*).Untrusted Data Boundary: External GitHub issues/PRs/logs, Cloudflare tail logs, and downstream MCP-2 responses are wrapped as untrusted external content to defend against prompt injection.
OAuth 2.1 Family Rotation & Replay Protection: Refresh token reuse outside the 60-second grace window revokes the entire token family immediately.
Optional ops-mcp Sidecar Federation (MCP-2)
Federate internal HTTP or local stdio MCP servers (such as uarlouski/ssh-mcp-server bridged via mcp-proxy on isolated ops_net) without exposing SSH keys to /workspaces:
Create
docker/ops-ssh/containing your restrictedconfig.jsonand scoped SSH key(s).Copy
docker/ops-mcp-config.example.jsontodocker/ops-mcp-config.jsonand reviewreadonlyTools,mutatingTools, anddeniedTools.Uncomment
./ops-mcp-config.json:/etc/gemini-bastion/ops-mcp-config.json:roindocker/docker-compose.ymland setDOWNSTREAM_MCPS_FILE=/etc/gemini-bastion/ops-mcp-config.jsonin.env.Build and start with the
opsprofile (usesdocker/Dockerfile.ops-mcpwith pre-installed binaries soops-mcpruns offline oninternal: trueops_netas non-rootnode):docker compose -f docker/docker-compose.yml --profile ops up -d --build
Policy enforcement: readonlyTools run in infra_inspect; mutatingTools must be staged via stage_mutation_plan and executed via publish_changes; deniedTools and unlisted tools are strictly rejected.
Webhook Notifications
Set NOTIFY_WEBHOOK_URL in .env to receive SecretScrubber-sanitized JSON POST webhooks whenever background jobs finish/fail/cancel or when staged mutation plans execute or roll back.
Pre-Release GitHub Metadata & Media Checklist
When publishing to GitHub, configure the repository front page with:
About:
Self-hosted OAuth 2.1 Streamable HTTP MCP bastion for Web Gemini, Claude & ChatGPT. Sandboxed git workspaces, Codex SDK, Cloudflare ops & 10-tool/1-gate funnel.Topics:
mcp,model-context-protocol,gemini,claude,codex,oauth21,streamable-http,cloudflare-tunnel,ai-agents,devops,self-hosted,typescriptRecommended Visual Assets (
docs/assets/):demo-gemini-pr.gif— 15s Web Gemini workflow fromcode_explore->code_patch-> singlepublish_changesPR approvalportal-and-oauth.png—GET /Public Gateway Portal & OAuth 2.1 consent viewadmin-mobile-pwa.png—/adminmobile PWA cockpit showing KPI Pulse Strip & SSE live job stream
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The bridge from K2 agents through Wrangler to your master AI - safe, approval-gated Cloudflare ops.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Cloud console for a fleet of AI coding agents running on your own machines. OAuth.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI coding agents to run Kubernetes inspection and Terraform plan/apply operations inside ephemeral gVisor-sandboxed jobs with short-lived, narrowly-scoped credentials, while routing destructive changes through a human approval gate.3-
- AlicenseNot gradedqualityCmaintenanceEnables LLM clients to search, read, and patch a trusted source repository with rollback-safe edits, Git operations, and allowlisted validation over stdio or OAuth-protected HTTP. Keeps secrets and arbitrary shell access out of reach while enforcing bounded batched I/O and operator-controlled workspace trust.MIT
- AlicenseNot gradedqualityAmaintenanceGives web-based AI chat clients a governed, OAuth-gated operating surface over a single MCP endpoint, letting them read and edit files, run whitelisted shell commands, search, inspect Git and SQLite, drive browsers and DevTools, manage background jobs, and reach localhost services on your own machine.MIT
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI assistants and local IDEs to securely operate a local machine through an OAuth-gated suite of 38 tools covering files, shell, search, Git, databases, browser automation, DevTools, background tasks, clipboard, localhost services, and Postman. Access is constrained by a command whitelist, folder allowlists, and rate limits so clients never receive unrestricted shell access.MIT