Document Secure MCP Tunnel setup and deployment boundaries

[yia-mw-agent]

Parent

• PRD: Dedicated FAVA Data Repo MCP Tunnel for ChatGPT #67

What to build

Document how operators connect a private FAVA Trails data repo to ChatGPT using OpenAI Secure MCP Tunnel and the dedicated gateway runtime. The documentation should make the intended shape unambiguous: one long-lived gateway per data repo, tunnel-client runs inside the operator environment, and ChatGPT connects through the OpenAI-hosted tunnel without requiring a public FAVA endpoint.

The docs should also state the v1 boundaries so future agents do not expand the design back into per-agent aggregation, per-machine registries, Tailscale Aperture proxying, Cloudflare Tunnel as the mainline path, public HTTPS hosting, or MachineWisdom-specific deployment runbooks.

Acceptance criteria

• Operator docs explain required environment/configuration for the dedicated gateway runtime, including FAVA_TRAILS_DATA_REPO, Trust Gate provider config, and optional scope hinting.
• Docs include repeatable OpenAI Secure MCP Tunnel validation steps using tunnel-client init, tunnel-client doctor, and tunnel-client run.
• Docs describe ChatGPT connector setup and expected discovery behavior, including using list_scopes and explicit trail_name.
• Docs explain that the gateway is data-repo-owned and long-lived, not agent-owned and not tied to a product working directory.
• Docs warn that private FAVA data should not be exposed through a public endpoint without separately designed authentication, authorization, and hosting controls.
• Docs explicitly mark per-agent aggregation, per-machine registries, Tailscale Aperture integration, Cloudflare Tunnel mainline support, WiseMachine host assumptions, and public HTTPS hosting as out of scope for this v1 path.

Blocked by

• Add a dedicated ChatGPT gateway runtime #64
• Expose and verify the gateway-safe MCP workflow #65

Delivery verification — 2026-09-07

All criteria are satisfied by merged PR #96 (6c5278a40a86246014901a88417f3455a46cdfcc). The new portable operator guide, linked from README, covers explicit repository ownership, ordinary principal identity, Trust Gate configuration/credentials/prompts, optional scope hinting, init/doctor/run validation, supervised lifecycle, ChatGPT tunnel connection and exact scope discovery, restart readback, and the explicit v1 exclusions. Public exposure requires separately designed controls.

The guide was checked against the actual FAVA CLI, installed tunnel-client help, and OpenAI's primary Secure MCP Tunnel documentation. Independent review accepted the exact integrated patch. All851 combined tests and required GitHub checks passed. The private deployment independently exercised no-tunnel preflight, ordinary governance, real review/sync, and actual connected-surface readback after restart.