PRD: Dedicated FAVA Data Repo MCP Tunnel for ChatGPT

[yia-mw-agent]

Problem Statement

FAVA Trails currently runs MCP servers as agent-owned stdio processes. That works for Claude/Codex/Hermes, but ChatGPT needs durable access to the FAVA data repo outside any one agent session. The goal is not to expose every agent's FAVA process, nor to build a per-machine registry. Operators need one long-lived, repo-owned FAVA MCP runtime per fava-trails-data repo, connected to ChatGPT through OpenAI Secure MCP Tunnel.

Solution

Add a documented long-lived "ChatGPT gateway" runtime for a single FAVA Trails data repo. The runtime is not owned by an agent, does not infer scope from a product working directory, and is started with explicit FAVA_TRAILS_DATA_REPO plus Trust Gate configuration. tunnel-client connects ChatGPT to this private MCP runtime over stdio or HTTP, using OpenAI's outbound tunnel path. Existing per-agent stdio registration remains unchanged.

User Stories

1. As a FAVA operator, I want one long-lived MCP runtime per data repo, so that ChatGPT can access durable FAVA memory.
2. As a ChatGPT user, I want to recall promoted thoughts, so that ChatGPT has the same memory as other agents.
3. As a ChatGPT user, I want to save draft thoughts, so that useful chat findings persist.
4. As a ChatGPT user, I want to propose truth through Trust Gate, so that shared memory remains governed.
5. As an operator, I want no public FAVA endpoint, so that private memory stays inside my environment.
6. As an operator, I want the runtime to be data-repo-owned, so that it is not tied to any agent process or working directory.
7. As a developer, I want existing stdio clients unchanged, so that Claude/Codex/Hermes do not regress.
8. As a maintainer, I want one shared MCP tool surface, so that schemas and behavior do not drift.
9. As an operator, I want startup checks, so that missing JJ, data repo, Trust Gate auth, or tunnel config is diagnosable.
10. As an operator, I want clear docs for OpenAI tunnel setup, so that ChatGPT connector validation is repeatable.
11. As a security reviewer, I want destructive/admin tools handled deliberately, so that ChatGPT write access does not imply unrestricted repo administration.
12. As an open-source user, I want no MachineWisdom host assumptions, so that the same pattern works for any private FAVA data repo.

Implementation Decisions

• Replace the native-public-HTTPS framing with OpenAI Secure MCP Tunnel as the primary transport.
• Add a long-lived gateway run mode or documented command profile for a single FAVA_TRAILS_DATA_REPO.
• Keep current per-agent stdio MCP behavior as the default path.
• Do not build a per-machine registry, dynamic agent registration, Aperture aggregation, or Cloudflare Tunnel path for v1.
• ChatGPT gateway scope resolution must not depend on a caller working directory. ChatGPT must use explicit trail_name, with list_scopes and optional FAVA_TRAILS_SCOPE_HINT for discovery.
• The gateway supports read and write workflows: recall, get_thought, save_thought, propose_truth, and sync.
• Admin/destructive tools such as rollback-style operations should be excluded or separately enabled by explicit configuration.
• Machine Wisdom's deployment is one long-lived gateway for the single Machine Wisdom fava-trails-data repo.

Testing Decisions

• Primary seam: end-to-end MCP behavior through the dedicated gateway runtime, covering list-tools, recall, save draft, and propose truth.
• Preserve existing handler and TrailManager tests for storage, Trust Gate, scope, conflict, and VCS behavior.
• Add startup/config tests for missing data repo, missing JJ, missing Trust Gate provider config, and clear runtime output.
• Add documented manual validation with tunnel-client doctor, tunnel-client run, and ChatGPT connector discovery.

Out of Scope

• Exposing every per-agent FAVA MCP process.
• Building a per-machine MCP registry.
• Tailscale Aperture integration.
• Cloudflare Tunnel as a mainline path.
• Public HTTPS hosting of private FAVA data.
• Redesigning thought lifecycle, Trust Gate semantics, or retrieval ranking.

Implementation Issues

• Add a dedicated ChatGPT gateway runtime #64
• Expose and verify the gateway-safe MCP workflow #65
• Document Secure MCP Tunnel setup and deployment boundaries #66

Further Notes

OpenAI Secure MCP Tunnel supports private MCP servers reachable over stdio or HTTP from the tunnel-client host, does not require inbound internet access, and is the right fit for this per-data-repo gateway design: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels