zgaetano/mcp-servers
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add README.md

Browse source
This commit is contained in:
zgaetano 2026-03-31 15:33:26 -04:00
parent 261ecc6034
commit f969862fa4
1 changed files with 95 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

95
README.md Normal file
View file

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