spec(052): mcpproxy behind an MCP tunnel — Anthropic + open-source recipes#485
Open
Dumbris wants to merge 2 commits into
Open
spec(052): mcpproxy behind an MCP tunnel — Anthropic + open-source recipes#485Dumbris wants to merge 2 commits into
Dumbris wants to merge 2 commits into
Conversation
Server-edition only. Adds a tunnel-safe mode (--tunnel-mode / tunnel.enabled config) for mcpproxy-server that hardens the /mcp listener for use as the upstream behind an Anthropic MCP Tunnel: agent-token-only auth, no Web UI on the tunneled port, /healthz enabled, banner log on startup. Ships the two-container compose recipe under examples/mcp-tunnel/ + a single deployment doc covering the auth-layer table (outer mTLS / inner TLS / agent token / upstream OAuth), day-2 ops (cert renewal, token rotation), and the limitations (not on claude.ai today, 10-tunnels-per-org cap, Research Preview). Four P1/P2 user stories with independent tests, 18 FRs, 7 measurable success criteria. Out of scope: personal-edition integration, replacing Anthropic's mcp-proxy image, per-end-user identity propagation, Helm chart, automated tunnel provisioning. Refs: spec/052
Extends scope from server-edition + Anthropic MCP Tunnels only to both editions + four recipes: - examples/mcp-tunnel-anthropic/ (server edition, Managed Agents) - examples/mcp-tunnel-cloudflared/ (both editions, OpenCode and friends) - examples/mcp-tunnel-tailscale/ (both editions, Funnel + Serve) - examples/mcp-tunnel-ngrok/ (both editions, ephemeral demos) Same --tunnel-mode / tunnel.enabled hardening applies to every recipe: agent-token-only auth on /mcp, no Web UI on tunneled port, /healthz enabled. The three open-source recipes specifically answer 'how can OpenCode users (and other non-Anthropic-platform clients) reach a private mcpproxy without inbound ports', since Anthropic MCP Tunnels are gated to Managed Agents + Messages API only. Seven user stories (P1: Anthropic + cloudflared + auth-bridges + tunnel- safe-mode; P2: Tailscale + day-2 ops; P3: ngrok). Twenty-three FRs. Eight measurable success criteria. References include Cloudflare, Tailscale, ngrok docs and OpenCode MCP servers docs. Spec 053 (mcpproxy expose CLI wrapping the tunnel daemons) is called out as deferred follow-up, gated on customer demand. Refs: spec/052
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 26203205167 --repo smart-mcp-proxy/mcpproxy-go
|
Member
Author
|
Critic (Codex) review — Dumbris's PR #485 |
Member
Author
|
Critic (Codex) review — Dumbris's PR #485 Strengths: Spec-only change with concrete tunnel recipes, explicit auth-boundary requirements, smoke-test obligations, and clear out-of-scope boundaries. CI is green for all non-skipped checks. Findings:
Checks: Provenance check: ok |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the spec for Spec 052 — documenting (and minimally supporting) how to expose mcpproxy through a tunnel so MCP clients on another machine can reach a private mcpproxy without inbound firewall holes.
Four recipes, both editions:
mcpproxy-serverinside a VPC via the two-containermcp-proxy+cloudflaredstack.One tunnel hostname fronts the full multiplexed
/mcpsurface; mcpproxy enforces auth via agent tokens; the tunnel only provides transport.What's in this PR
specs/052-mcp-tunnel-recipe/spec.md— feature specification (Draft) with P1 user stories for both Anthropic Managed Agents and open-source tunnel users.Spec only — no code changes yet. Ready for plan.
🤖 Generated with Claude Code