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:

Gateway returns 401 with WWW-Authenticate header pointing to resource metadata
Claude discovers /.well-known/oauth-protected-resource → finds authorization server
Claude discovers /.well-known/oauth-authorization-server → finds all OAuth endpoints
Claude calls /oauth/register (Dynamic Client Registration) to get a client_id
Claude opens /oauth/authorize in browser → you see a consent page → enter your password
Gateway issues an authorization code, redirects to Claude's callback
Claude exchanges the code at /oauth/token (with PKCE verification) → gets access + refresh tokens
Claude sends MCP requests to /mcp with Authorization: Bearer <token>
Tokens auto-refresh via the refresh token grant

Setup

Copy .env.example to .env and fill in your values
Set a strong OAUTH_PASSWORD — this is what you type in the consent page
Set OAUTH_ISSUER_URL to your public gateway URL (e.g., https://mcp.wilddragon.net)
Build and start: docker compose up -d --build
In claude.ai → Settings → Connectors → Add → paste https://mcp.wilddragon.net/mcp
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

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

4 KiB Raw Blame History