diff --git a/docs/gotchas.md b/docs/gotchas.md
index 5f628867..3bf7dd2d 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 6f707bff..83a66a6e 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