diff --git a/mcp-gateway/README.md b/mcp-gateway/README.md
new file mode 100644
index 0000000..ba8baf4
--- /dev/null
+++ b/mcp-gateway/README.md
@@ -0,0 +1,95 @@
+# MCP Gateway Stack
+
+Aggregates multiple MCP backend servers behind a single Streamable HTTP endpoint with **OAuth 2.1** authentication, exposed via Tailscale Funnel.
+
+## Architecture
+
+```
+claude.ai / Claude Mobile / Claude Code
+        │
+        │  OAuth 2.1 (PKCE + DCR)
+        ▼
+┌─────────────────────────────┐
+│  MCP Gateway Proxy (:4444)  │  ← mcp.wilddragon.net via Tailscale Funnel
+│  OAuth Provider + Aggregator│
+└────┬──────────┬─────────┬───┘
+     │          │         │
+     ▼          ▼         ▼
+  ERPNext    TrueNAS    Home
+  MCP        MCP        Assistant
+  (:32802)   (:8100)    MCP (:8200)
+```
+
+## OAuth 2.1 Flow
+
+When claude.ai connects to `https://mcp.wilddragon.net/mcp`:
+
+1. Gateway returns **401** with `WWW-Authenticate` header pointing to resource metadata
+2. Claude discovers `/.well-known/oauth-protected-resource` → finds authorization server
+3. Claude discovers `/.well-known/oauth-authorization-server` → finds all OAuth endpoints
+4. Claude calls `/oauth/register` (Dynamic Client Registration) to get a `client_id`
+5. Claude opens `/oauth/authorize` in browser → you see a consent page → enter your password
+6. Gateway issues an authorization code, redirects to Claude's callback
+7. Claude exchanges the code at `/oauth/token` (with PKCE verification) → gets access + refresh tokens
+8. Claude sends MCP requests to `/mcp` with `Authorization: Bearer <token>`
+9. Tokens auto-refresh via the refresh token grant
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your values
+2. **Set a strong `OAUTH_PASSWORD`** — this is what you type in the consent page
+3. Set `OAUTH_ISSUER_URL` to your public gateway URL (e.g., `https://mcp.wilddragon.net`)
+4. Build and start: `docker compose up -d --build`
+5. In claude.ai → Settings → Connectors → Add → paste `https://mcp.wilddragon.net/mcp`
+6. Complete the OAuth flow when prompted (enter your gateway password)
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OAUTH_ISSUER_URL` | Yes | `https://mcp.wilddragon.net` | Public URL of the gateway |
+| `OAUTH_PASSWORD` | Yes | — | Password for the consent page |
+| `OAUTH_ACCESS_TOKEN_TTL` | No | `3600` | Access token lifetime (seconds) |
+| `OAUTH_REFRESH_TOKEN_TTL` | No | `2592000` | Refresh token lifetime (seconds) |
+| `ERPNEXT_URL` | Yes | — | ERPNext instance URL |
+| `ERPNEXT_API_KEY` | Yes | — | ERPNext API key |
+| `ERPNEXT_API_SECRET` | Yes | — | ERPNext API secret |
+| `TRUENAS_URL` | Yes | — | TrueNAS API URL |
+| `TRUENAS_API_KEY` | Yes | — | TrueNAS API key |
+| `HASS_URL` | Yes | — | Home Assistant URL |
+| `HASS_TOKEN` | Yes | — | Home Assistant long-lived token |
+
+## Endpoints
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `GET /health` | None | Health check |
+| `GET /status` | Bearer | Detailed backend status |
+| `GET /.well-known/oauth-protected-resource` | None | RFC 9728 resource metadata |
+| `GET /.well-known/oauth-authorization-server` | None | RFC 8414 server metadata |
+| `POST /oauth/register` | None | RFC 7591 dynamic client registration |
+| `GET /oauth/authorize` | None | Authorization page (consent form) |
+| `POST /oauth/token` | None | Token exchange / refresh |
+| `POST /mcp` | Bearer | MCP JSON-RPC endpoint |
+
+## Testing
+
+```bash
+# Health check
+curl https://mcp.wilddragon.net/health
+
+# Check OAuth metadata
+curl https://mcp.wilddragon.net/.well-known/oauth-authorization-server
+
+# Check resource metadata
+curl https://mcp.wilddragon.net/.well-known/oauth-protected-resource
+
+# Verify 401 on unauthenticated MCP request
+curl -X POST https://mcp.wilddragon.net/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
+```
+
+## Adding New Backends
+
+Add a new `MCP_BACKEND_<NAME>` env var to the gateway service in `docker-compose.yml` and rebuild. Tools will be auto-discovered and prefixed with the backend name.