ci: add GitHub Pages deployment workflow and improve documentation

.github/workflows/check.yaml

@@ -30,3 +30,26 @@ jobs:
       - uses: dominikh/[email protected]
         with:
           install-go: false
+
+  docs-check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install docs dependencies
+        run: npm ci
+
+      - name: Lint documentation
+        run: npm run lint

.github/workflows/docs.yaml

@@ -0,0 +1,61 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build documentation
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  "files.trimTrailingWhitespace": true,
+  "[css]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "files.trimTrailingWhitespace": false,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[tsx]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

README.md

@@ -7,7 +7,7 @@
 ## Overview
 
 - **Drop-in OAuth 2.1/OIDC gateway for MCP servers — put it in front, no code changes.**
-- **Your IdP, your choice**: Google, GitHub, or any OIDC provider — e.g. Okta, Auth0, Azure AD, Keycloak — plus optional password with allow-list.
+- **Your IdP, your choice**: Google, GitHub, or any OIDC provider — e.g. Okta, Auth0, Azure AD, Keycloak — plus optional password.
 - **Publish local MCP servers safely**: Supports all stdio, SSE, and HTTP transports. For stdio, traffic is converted to `/mcp`. For SSE/HTTP, it’s proxied as-is. Of course, with authentication.
 - **Verified across major MCP clients**: Claude, Claude Code, ChatGPT, GitHub Copilot, Cursor, etc. — the proxy smooths client-specific quirks for consistent auth.
 
@@ -36,15 +36,15 @@ To proxy SSE or HTTP transport, specify a URL; to use the stdio transport, speci
 
 | MCP Client        | Status | Notes                                            |
 | ----------------- | ------ | ------------------------------------------------ |
-| Claude - Web      | ✅      |                                                  |
-| Claude - Desktop  | ✅      |                                                  |
-| Claude Code       | ✅      |                                                  |
-| ChatGPT - Web     | ✅      | Need to implement `search` and `fetch` tools.(1) |
-| ChatGPT - Desktop | ✅      | Need to implement `search` and `fetch` tools.(1) |
-| GitHub Copilot    | ✅      |                                                  |
-| Cursor            | ✅      |                                                  |
+| Claude - Web      | ✅     |                                                  |
+| Claude - Desktop  | ✅     |                                                  |
+| Claude Code       | ✅     |                                                  |
+| ChatGPT - Web     | ✅     | Need to implement `search` and `fetch` tools.(1) |
+| ChatGPT - Desktop | ✅     | Need to implement `search` and `fetch` tools.(1) |
+| GitHub Copilot    | ✅     |                                                  |
+| Cursor            | ✅     |                                                  |
 
-- *1: https://platform.openai.com/docs/mcp
+- \*1: https://platform.openai.com/docs/mcp
 
 ## 🚀 Usage
 
@@ -97,17 +97,20 @@ docker run --rm --net=host \
 ### Provider Setup
 
 #### Google OAuth Setup
+
 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
 2. Create a new project or select an existing one
 3. Create OAuth consent screen
 4. Credentials → Create credentials → OAuth client ID (Web application)
 5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback`
 
 #### GitHub OAuth Setup
+
 1. Go to the [Register new OAuth App](https://github.com/settings/applications/new)
 2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback`
 
 #### OIDC Provider Setup
+
 1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.)
 2. Create a new client application
 3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback`

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.prettierrc

@@ -0,0 +1 @@
+{}

docs/docs/client-integration.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 4
+---
+
+# MCP Client Integration
+
+Learn how to connect various MCP clients to your authenticated MCP server.
+
+## Supported Clients
+
+MCP Auth Proxy has been verified to work with all major MCP clients:
+
+| MCP Client        | Status | Notes                                           |
+| ----------------- | ------ | ----------------------------------------------- |
+| Claude (Web)      | ✅     | Full compatibility                              |
+| Claude (Desktop)  | ✅     | Full compatibility                              |
+| Claude Code       | ✅     | Full compatibility                              |
+| ChatGPT (Web)     | ✅     | Requires `search` and `fetch` tools [¹](#notes) |
+| ChatGPT (Desktop) | ✅     | Requires `search` and `fetch` tools [¹](#notes) |
+| GitHub Copilot    | ✅     | Full compatibility                              |
+| Cursor            | ✅     | Full compatibility                              |
+
+## Claude Integration
+
+### Claude Desktop & Web
+
+1. Go to Claude Settings → Connectors
+2. Add custom connector
+3. Enter URL: `https://{your-domain}/mcp`
+4. You'll be redirected to authenticate
+
+### Claude Code
+
+Configure in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-protected-server": {
+      "url": "https://{your-domain}/mcp"
+    }
+  }
+}
+```
+
+## ChatGPT Integration
+
+### Prerequisites
+
+ChatGPT requires your MCP server to implement `search` and `fetch` tools.
+
+### Configuration
+
+1. Go to ChatGPT Settings → Connectors
+2. Create
+3. Fill in the form:
+   - **MCP Server URL**: `https://{your-domain}/mcp`
+   - **Authentication**: OAuth
+4. Complete authentication flow
+
+## GitHub Copilot Integration
+
+### VS Code Extension
+
+Configure in `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "my-protected-server": {
+      "url": "https://{your-domain}/mcp",
+      "type": "http"
+    }
+  },
+  "inputs": []
+}
+```
+
+## Cursor Integration
+
+### Configuration
+
+Configure in Cursor settings:
+
+```json
+{
+  "mcpServers": {
+    "my-protected-server": {
+      "url": "https://{your-domain}/mcp"
+    }
+  }
+}
+```