# 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.