Architecture

MCP core and ingress paths

MCP host
   │
   ├── stdio (native Windows/macOS)
   ├── Streamable HTTP (Linux; loopback/private by default)
   ├── OpenAI Secure MCP Tunnel (optional ChatGPT ingress)
   ├── Cloudflare Tunnel (Linux v0.24.0 stable ingress)
   └── Cloudflare Tunnel (native macOS v0.24.1)
               │
               ▼
          ServerFS MCP Core
               │  scoped policy
               ▼
       explicitly configured workdirs

The MCP core and tool contract are host-neutral. Generic Linux HTTP publication is opt-in and binds loopback by default; public exposure requires explicit Host policy plus a TLS/authentication ingress boundary. The OpenAI Tunnel remains an optional authenticated outbound-only adapter. The v0.24.0 Linux Cloudflare Tunnel overlay adds a separate cloudflared connector on the private ServerFS network and dedicated tunnel egress network, without host port publication; it requires independent API Key/OAuth admission and is published. Native macOS Cloudflare is a separate v0.24.1 feature: a loopback HTTP origin and Connector use the existing app-associated SMAppService LaunchAgent mechanism, with private credentials and exact Host admission. Isolated staging passed HTTPS 401/200, 11-tool discovery, read-only negative cases, 65.1-second SSE and fresh-session recovery on 8/8 Connector restarts; the old session returned 404. No SSE replay is claimed. Login Items architecture parity was reviewed, but logout/login and reboot were not performed. Native Windows Cloudflare shipped in v0.24.2: two independent same-user Task Scheduler owners passed public ChatGPT tools and cross-ingress file operations. The real public SSE gate passed with 75.0/70.0/65.0-second holds, approximately 15-second keepalives, same-session tools/list 200 (27 tools), and new-session 200. The operator waived full-generation restart/recovery on 2026-11-10; it was not tested and did not pass. Windows HTTP origin and cloudflared share one kill-on-close Job generation. This is architecture-equivalent Windows acceptance, not a Connector-only restart pass; an older in-memory session is not guaranteed to survive or replay. The owners share one Agent Bridge/Repo Ops service; preserve it while Cloudflare depends on it. See Cloudflare Tunnel, Windows Native and macOS Native. In the Compose topology, serverfs-mcp also joins serverfs_file_ingress, a second Docker internal:true network; cloudflared never joins it. The main MCP container still has no general Internet egress.

Optional ChatGPT file-ingress path

ChatGPT file parameter
   │
   │ temporary HTTPS URL
   ▼
ServerFS MCP
   │ dedicated internal network only
   ▼
serverfs-file-ingress
   │ policy-checked HTTPS/443 egress only
   ▼
Temporary file host

The sidecar is opt-in. It has no workdir mounts, OpenAI/tunnel credentials, or published port. The main MCP container never receives Internet egress; it sends only the temporary URL and byte ceiling to the sidecar. Host authorization is either an exact administrator-configured hostname or the separately enabled constrained OpenAI Azure Blob account family measured from real ChatGPT file parameters. Generic wildcards are rejected. The sidecar then validates globally routable DNS answers, pins the connection to a validated IP while verifying TLS for the original hostname, revalidates every redirect, and enforces timeout and byte ceilings before returning raw bytes.

Optional static API Key path

MCP client
   │ Authorization: Bearer <key>
   │ or /mcp?key=<key>
   ▼
ServerFS static API Key ASGI boundary
   ▼
Streamable HTTP MCP app
   ▼
existing ServerFS workdir policy

The v0.17 API Key path is a small HTTP ingress wrapper around the SDK Streamable HTTP app. It creates no authorization service, database, user identity, scope model or provider egress. API Key and built-in OAuth are mutually exclusive. Query-key compatibility is supported, but the ServerFS runner disables its own default Uvicorn access log in this mode so a secret-bearing URL is not printed by ServerFS itself. See Static API Key.

Optional OAuth path

MCP client
   │ OAuth bearer
   ▼
ServerFS MCP Resource Server
   │ private introspection only
   ▼
serverfs-auth
   │
   ├── GitHub
   ├── DingTalk
   ├── Feishu / Lark
   └── WeChat Open Platform

serverfs-auth is a separately deployed, non-root service with its own writable SQLite state and OAuth-only egress network. Provider credentials never enter serverfs-mcp; the MCP container does not join the OAuth egress network. The Resource Server accepts only ServerFS-issued opaque tokens bound to the configured MCP resource. Admission is exact and default-deny, then the existing workdir policy applies unchanged.

OAuth is Linux remote-HTTP deployment state, not part of native Windows/macOS stdio. See OAuth 2.1 for the public TLS/reverse-proxy shape, provider callbacks, client registration and Tunnel compatibility boundary.

Optional Deterministic Repo Ops path (v0.23+; current v0.24.0)

ServerFS MCP container
   │  structured repo.* RPC
   ▼
authenticated host Bridge transport
   │
   ├── fixed Git inspection / commit / push semantics
   └── operator-defined integrity-pinned named actions

Repo Ops reuses the host Bridge transport, host workdir path, current-user Git credential context, and shared writer lease, but it does not enter the Agent execution path. No model/runtime is selected, no Agent task/session is created, and no provider adapter is invoked. Repo Ops and Agent delegation are authorized independently per workdir. Linux Host Bridge support shipped in v0.23.0, validated native Apple Silicon macOS support followed in v0.23.1, and v0.23.2 adds validated native Windows 11 x64 support. See Deterministic Repo Ops.

Optional Agent path

ServerFS MCP container
   │
   │ read-only Unix socket mount
   ▼
Host Agent Bridge
   │
   ├── Codex
   ├── Claude Code
   ├── Qoder
   └── ACP v1 profiles (operator-configured)

The Bridge runs as a user-scoped host service and owns its runtime socket, locks, installed releases, configuration, and state outside the repository checkout.

Optional Jev advisory path

Agent task / model-advice request / provider approval
   │
   ▼
Host Agent Bridge
   │  minimized structured state
   ▼
TypeSafe Jev API
   │  probabilities / confidence / Noul
   ▼
Advisory result only

Jev runs from the host Bridge, not the MCP container. Task Preflight and Runtime Router share one task-submission request; Model Advisor can run before submission only after native model discovery; Approval Advisor runs only after a provider creates an approval request. These outputs never become authorization, runtime-selection, or model-selection authority.

Native persistent lifecycle

Native deployments keep persistence outside the MCP protocol surface and within the current user’s OS lifecycle:

Windows v0.14.0+
Task Scheduler 2.0 (InteractiveToken · LeastPrivilege)
   │  logon trigger + 1-minute time-trigger heartbeat
   ▼
windowless watchdog
   │  Job Object containment + bounded restart
   ▼
managed runner
   │  bounded Tunnel-generation restart
   ▼
tunnel-client -> supervisor -> ServerFS / Agent Bridge

macOS v0.13.2
SMAppService + per-user LaunchAgents
   ▼
persistent Tunnel / Agent Bridge

The Windows v0.14 lifecycle is deliberately not an SCM/LocalSystem service: install, runtime, maintenance and removal stay current-user and non-elevated. A fresh task is registered disabled; service start enables it, while service stop disables it before ending the current action so the heartbeat cannot undo an intentional stop. IgnoreNew plus the native ownership mutex preserve exactly one managed Windows Tunnel lifecycle.

Capability boundaries

ServerFS exposes narrow operations rather than a generic execution primitive:

• filesystem read tools
• guarded file mutations
• bounded whole-file binary transfer
• optional isolated ChatGPT file ingress
• optional one-secret static API Key boundary for Linux remote HTTP
• optional OAuth 2.1 Resource Server + isolated identity broker for Linux remote HTTP
• structured Agent task RPC, model discovery and request-scoped model override
• Deterministic Repo Ops: Linux Host Bridge since v0.23.0, validated native Apple Silicon macOS since v0.23.1, and validated native Windows 11 x64 since v0.23.2; bounded Git inspection, fixed named actions, explicit-file commit, exact current-upstream push, and fixed npm release actions for the validated package.json release shape
• optional host-side Jev advisory decisions

The stable v0.24.0 release retains the existing 11 / 13 / 21 / 23 tool combinations and can independently add four Repo Ops tools on Linux Host Bridge, validated native Apple Silicon macOS, and validated native Windows 11 x64: 15 tools for Repo Ops-only, 17 with binary transfer, 25 with Agent delegation, and 27 when binary, Agent and Repo Ops are all enabled. Repo Ops and Agent delegation are gated separately; Repo Ops never creates an Agent task and accepts no generic shell, argv, environment, remote, ref or force input. Linux bootstrap/internal and public ChatGPT MCP E2E remain the v0.23.0 baseline; v0.23.1 adds native macOS live acceptance; v0.23.2 adds Windows process-tree containment, reparse-point fail-closed behavior, Git-for-Windows portability, and live public MCP acceptance. See Deterministic Repo Ops for the full contract and evidence. Jev remains an internal Agent Bridge advisor rather than an MCP capability surface.