From 5100bbe7b4e0b840026ce25619b989050569e1c9 Mon Sep 17 00:00:00 2001
From: Waishnav <86405648+Waishnav@users.noreply.github.com>
Date: Mon, 31 Aug 2026 21:46:22 +0530
Subject: [PATCH] docs: document Tailscale Funnel root proxy setup

---
 docs/gotchas.md | 13 +++++++++++++
 docs/setup.md   | 10 ++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/gotchas.md b/docs/gotchas.md
index 5f6288678..3bf7dd2d8 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -65,6 +65,19 @@ If you saved the wrong value:
 npx @waishnav/devspace config set publicBaseUrl https://your-tunnel-host.example.com
 ```
 
+## Tailscale Funnel `/mcp` Returns 404
+
+Proxy the whole DevSpace server from the Funnel root:
+
+```bash
+tailscale funnel --bg 7676
+```
+
+Do not use `--set-path=/mcp`. Tailscale removes a configured mount path before
+proxying to the local service, so a public `/mcp` request can otherwise arrive
+at DevSpace as `/`. DevSpace also needs OAuth routes outside `/mcp`, so serving
+the whole local origin is the correct setup.
+
 ## Tunnel URL Changed
 
 Temporary tunnels often change URLs between runs.
diff --git a/docs/setup.md b/docs/setup.md
index 6f707bff8..83a66a6eb 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -77,6 +77,16 @@ reverse proxy first and point it at:
 http://127.0.0.1:7676
 ```
 
+For Tailscale Funnel, proxy the whole DevSpace server from the root path:
+
+```bash
+tailscale funnel --bg 7676
+```
+
+Do not mount Funnel only at `/mcp` with `--set-path=/mcp`. DevSpace also serves
+OAuth discovery and authorization routes outside `/mcp`, and a path mount can
+strip `/mcp` before the request reaches DevSpace.
+
 Enter the public origin without `/mcp`:
 
 ```text