# zenvx-mcp

Secure self-hosted remote MCP server — Python (FastMCP, streamable HTTP) behind a Cloudflare Tunnel with bearer-token auth. Zero inbound ports.

**Live endpoint:** `https://mcp.zenvx.in/mcp` (Bearer token required)

## Architecture

```
MCP client → Cloudflare (TLS + WAF) → cloudflared tunnel → 127.0.0.1:8765 → laptop
```

## Tools

| Tool | Description |
|---|---|
| `ping` | Health check |
| `list_dir` | List a directory under the sandbox root |
| `read_file` | Windowed text-file read (offset/limit) |
| `write_file` | Write or append UTF-8 files (logged) |
| `run_shell` | Full shell access — **OFF** unless `MCP_ALLOW_SHELL=true`; every call logged; 120s cap |

## Security model

1. **Cloudflare Tunnel** — outbound-only; no open inbound ports; TLS + DDoS protection free
2. **Bearer token** — every request must carry `Authorization: Bearer <token>` (`openssl rand -hex 32`)
3. **Cloudflare Access** (recommended) — Zero Trust policy at the edge, so a leaked token alone is useless
4. **Sandbox root** — file tools cannot escape `MCP_FS_ROOT`
5. **Non-root systemd user** — unit hardening: `NoNewPrivileges`, `PrivateTmp`, `ProtectSystem`

## Repo layout

| File | Purpose |
|---|---|
| `server.py` | MCP server (FastMCP + bearer-auth middleware) |
| `requirements.txt` | `mcp` SDK + `uvicorn` |
| `cloudflared-config.yml` | Tunnel ingress: `mcp.zenvx.in` → `localhost:8765` |
| `zenvx-mcp.service` | systemd unit |
| `zenvx-mcp.env.example` | Env template — copy to `/etc/zenvx-mcp.env`, `chmod 600` |
| `SETUP.md` | Full setup guide: venv → token → systemd → tunnel → Access → clients |

## Quick start

```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
python server.py   # serves 127.0.0.1:8765/mcp — front it with cloudflared, never bind 0.0.0.0
```

Full instructions, Cloudflare Tunnel/Access steps, client configs (Claude Desktop, Notion MCP connector, MCP Inspector), and the Windows variant: **[SETUP.md](SETUP.md)**