How openai/tunnel-client works
Secure MCP Tunnel is a customer-run Go agent that keeps a private MCP server off the public internet while connecting it to OpenAI-hosted products. Its main workflow is to accept local MCP traffic, dispatch requests through a control-plane tunnel, and return responses; operators can inspect readiness and runtime behavior through a local admin UI. The repository also includes OAuth discovery, Harpoon-mediated HTTP tools, bundled cloudflared supervision, and Codex-managed runtime support. Wiring is grounded in the sampled app modules; some internal request-level handoffs are not shown.
Main entry points: App.svelte Admin UI shell · api.ts UI API client · runtimeapp/app.go Runtime composition · app/app.go Full-client composition
Components 25
Tunnel runtime
- Runtime composition
pkg/runtimeapp/app.go - Full-client composition
pkg/app/app.go - Cloudflared supervisor
pkg/cloudflared/runtime/supervisor.go
Runtime services
- Control-plane client
pkg/controlplane/internal/tunnel_service_client.go - MCP dispatcher
pkg/dispatcher/internal/processor.go - MCP client transport
pkg/mcpclient/serialized_forwarding_transport.go - OAuth discovery
pkg/oauth/discovery.go - Harpoon adapter
pkg/harpoon/server.go - Harpoon tools
pkg/runtimeharpoon/server.go - Local proxy
pkg/localproxy/localproxy.go
Operations UI
- Admin services
pkg/adminui/startup.go - Admin UI shell
adminui/src/App.svelte - UI API client
adminui/src/lib/api.ts - Overview panel
adminui/src/components/OverviewPanel.svelte - Metrics panel
adminui/src/components/MetricsPanel.svelte - OAuth panel
adminui/src/components/OAuthPanel.svelte - Harpoon panel
adminui/src/components/HarpoonPanel.svelte - System panel
adminui/src/components/SystemPanel.svelte - Logs panel
adminui/src/components/LogsPanel.svelte - Codex panel
adminui/src/components/CodexPanel.svelte
Codex management
- Codex runtime manager
pkg/codexplugin/manager.go - Managed runtime session
pkg/codexplugin/session/session.go
Other components
- Operator
- Private MCP server
- OpenAI tunnel service
Connections 31
- Private MCP server → MCP client transport: serves MCP
README.md - MCP client transport → MCP dispatcher: forwards requests
- MCP dispatcher → Control-plane client: polls tunnel
- Control-plane client → OpenAI tunnel service: exchanges tunnel data
README.md - Runtime composition → Control-plane client: wires
pkg/runtimeapp/app.go - Runtime composition → MCP dispatcher: wires
pkg/runtimeapp/app.go - Runtime composition → MCP client transport: wires
pkg/runtimeapp/app.go - Runtime composition → OAuth discovery: wires
pkg/runtimeapp/app.go - Runtime composition → Harpoon tools: wires
pkg/runtimeapp/app.go - Full-client composition → Admin services: wires
pkg/app/app.go - Full-client composition → Harpoon adapter: wires
pkg/app/app.go - Full-client composition → Cloudflared supervisor: starts supervisor
pkg/app/app.go - Harpoon adapter → Harpoon tools: adapts
pkg/harpoon/server.go - Operator → Admin UI shell: opens dashboard
README.md - Admin UI shell → Admin services: requests status
- Admin UI shell → Overview panel: renders
adminui/src/App.svelte - Admin UI shell → Metrics panel: renders
adminui/src/App.svelte - Admin UI shell → OAuth panel: renders
adminui/src/App.svelte - Admin UI shell → Harpoon panel: renders
adminui/src/App.svelte - Admin UI shell → System panel: renders
adminui/src/App.svelte - Admin UI shell → Logs panel: renders
adminui/src/App.svelte - Admin UI shell → Codex panel: renders
adminui/src/App.svelte - Overview panel → UI API client: fetches status
adminui/src/components/OverviewPanel.svelte - Metrics panel → UI API client: fetches metrics
adminui/src/components/MetricsPanel.svelte - OAuth panel → UI API client: fetches OAuth
adminui/src/components/OAuthPanel.svelte - Harpoon panel → UI API client: fetches targets
adminui/src/components/HarpoonPanel.svelte - System panel → UI API client: fetches system data
adminui/src/components/SystemPanel.svelte - Logs panel → UI API client: fetches logs
adminui/src/components/LogsPanel.svelte - Codex panel → UI API client: requests Codex data
adminui/src/components/CodexPanel.svelte - Codex panel → Codex runtime manager: manages runtimes
- Codex runtime manager → Managed runtime session: starts sessions
pkg/codexplugin/manager.go