Per-server oauth flow and massive refactoring (#20)

Adds OAuth for external MCP services and cleans up the auth code.

After Google login, users see a page listing services that need OAuth
(Linear, GitHub, etc). They can connect now or skip and do it later at
/my/tokens. Tokens get refreshed 5 min before expiry so they don't break
mid-session when users are in Claude.

Refactored the monolithic auth/oauth code into separate packages - oauth
for provider setup, googleauth for Google-specific stuff, browserauth
for session types, auth for the service OAuth client. Handlers split up
too. Everything uses dependency injection now.

Author: dgellow

.github/workflows/ci.yml

@@ -63,40 +63,8 @@ jobs:
     - name: Run unit tests
       run: go test -v ./internal/... ./cmd/...
 
-    - name: Build mcp-front CLI
-      run: go build -o mcp-front ./cmd/mcp-front
-
     - name: Validate config files
-      run: |
-        echo "Validating all config files in the repository..."
-        failed=0
-        
-        # Check root level config files
-        for config in *.json; do
-          if [[ -f "$config" ]]; then
-            echo "Checking $config..."
-            if ! ./mcp-front -validate -config "$config"; then
-              failed=1
-            fi
-          fi
-        done
-        
-        # Check integration test config files
-        for config in integration/config/*.json; do
-          if [[ -f "$config" ]]; then
-            echo "Checking $config..."
-            if ! ./mcp-front -validate -config "$config"; then
-              failed=1
-            fi
-          fi
-        done
-        
-        if [[ $failed -eq 1 ]]; then
-          echo "❌ Config validation failed for one or more files"
-          exit 1
-        else
-          echo "✅ All config files validated successfully"
-        fi
+      run: make lint-config
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3

CLAUDE.md

@@ -56,6 +56,8 @@ mcp-front is a Go-based OAuth 2.1 proxy server for MCP (Model Context Protocol)
 - **Define interfaces where they are used** - Not in the package that implements them
 - **Avoid circular imports** - Use interface segregation in separate packages when needed
 - **Dependency injection over getter methods** - Pass dependencies to constructors
+- **Functional core, imperative shell** - Prefer pure functions for business logic, keep side effects (I/O, state mutations) at the boundaries. Makes code more testable and reasoning easier.
+- **Upstream lifecycle control** - Manage goroutines, servers, and background processes from the application root. Library code should expose Start/Stop methods, not start things autonomously.
 
 ### 🎯 Core Development Principles (from Zig Zen)
 
@@ -115,7 +117,7 @@ LOG_FORMAT="text"           # json or text
 
 #### Updating OAuth scopes
 
-1. Check `internal/oauth/auth.go` for current scopes
+1. Check `internal/googleauth/google.go` for current scopes
 2. Use standard OpenID Connect scopes (not Google-specific URLs)
 3. Update tests to verify new scopes work
 
@@ -129,14 +131,24 @@ LOG_FORMAT="text"           # json or text
 
 ```
 internal/
-├── config/      # Configuration parsing and validation
-├── oauth/       # OAuth 2.1 implementation with fosite
-├── server/      # HTTP server and middleware
-├── client/      # MCP client management
-└── logging.go   # Structured logging setup
-
-integration/     # Integration tests (OAuth, security, scenarios)
-cmd/mcp-front/   # Main application entry point
+├── config/         # Configuration parsing and validation
+├── oauth/          # OAuth 2.1 provider, JWT, middleware
+├── googleauth/     # Google OAuth integration (pure functions)
+├── adminauth/      # Admin authorization logic
+├── browserauth/    # Browser session types (SessionCookie, AuthorizationState)
+├── oauthsession/   # OAuth session types for fosite
+├── servicecontext/ # Service authentication context utilities
+├── server/         # HTTP server, handlers, and middleware
+├── client/         # MCP client management and session handling
+├── auth/           # Service OAuth client for upstream authentication
+├── crypto/         # Encryption, HMAC, token signing utilities
+├── storage/        # Storage abstraction (memory, Firestore)
+├── inline/         # Inline MCP server implementation
+├── mcpfront.go     # Main application orchestration (imperative shell)
+└── [utility packages: cookie, email, envutil, json, jsonrpc, log, sse, testutil]
+
+integration/        # Integration tests (OAuth, security, scenarios)
+cmd/mcp-front/      # Main application entry point
 ```
 
 ### Testing Guidance
@@ -153,6 +165,7 @@ cmd/mcp-front/   # Main application entry point
 3. Don't create new auth patterns - use existing OAuth or bearer token auth
 4. Don't modify git configuration
 5. Don't create README files proactively
+6. **Variable shadowing package names** - `config.MCPClientConfig is not a type` means a variable named `config` is shadowing the package. Always check for variables that shadow imported package names
 
 ### When Working on Features
 

Makefile

@@ -3,14 +3,20 @@ doc:
 
 format:
 	go fmt ./...
+	# go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...
+	modernize -fix -test ./...
 	cd docs-site && npm run format
 
 lint:
 	staticcheck ./...
 	golangci-lint run ./...
 
+lint-config:
+	go build -o cmd/mcp-front/mcp-front ./cmd/mcp-front
+	./scripts/validate-configs.sh
+
 build:
 	go build -o mcp-front ./cmd/mcp-front
 	cd docs-site && npm run build
 
-.PHONY: doc format build lint
+.PHONY: doc format build lint lint-config

README.md

@@ -33,7 +33,7 @@ mcp-front is an authentication proxy that sits between Claude.ai and your MCP se
 
 - **Single sign-on** via Google OAuth for all MCP tools
 - **Domain validation** to restrict access to your organization
-- **Per-user tokens** for services like Notion
+- **Per-user authentication** for services like Notion and Stainless (via OAuth or manual tokens)
 - **Session isolation** so multiple users can share infrastructure
 
 ## Why use mcp-front?
@@ -52,7 +52,7 @@ With mcp-front:
 
 1. Claude.ai connects to `https://your-domain.com/<service>/sse`
 2. mcp-front validates the user's OAuth token
-3. If the server needs a user token, prompts via `/my/tokens`
+3. If a service requires user authentication, `mcp-front` will guide the user through a one-time setup (via an OAuth consent screen or a manual token entry page).
 4. Proxies requests to the configured MCP server
 5. For stdio servers, each user gets an isolated process
 
@@ -150,16 +150,24 @@ docker run -d -p 8080:8080 \
 
 mcp-front uses explicit JSON syntax `{"$env": "VAR_NAME"}` for environment variables throughout its configuration. This deliberate choice eliminates the ambiguity and risks inherent in shell-style variable substitution. When configs pass through multiple layers of tooling and scripts, traditional `$VAR` syntax can expand unexpectedly, causing security issues and debugging nightmares. The JSON format ensures your configuration remains exactly as written until mcp-front processes it, providing predictable behavior across all deployment environments. For per-user authentication, `{"$userToken": "{{token}}"}` follows the same principle, keeping user credentials cleanly separated from system configuration.
 
-### Per-user tokens
+## Service Authentication (Per-User Tokens)
 
-Some MCP servers are better to use with each users having their own integration token (e.g., Notion). Configure with:
+Some MCP servers, like Notion or Stainless, require each user to provide their own individual API key or grant access via OAuth. `mcp-front` automates this process.
 
+When a service is configured with `requiresUserToken: true`, `mcp-front` will guide the user through a one-time setup for that service after their initial Google login. This is handled in one of two ways, depending on the service's configuration.
+
+### Manual Token Entry
+
+For services that require a manually generated API key, you can configure `mcp-front` to prompt the user for it on a secure web page.
+
+**Configuration:**
 ```json
 {
   "notion": {
     "transportType": "stdio",
     "requiresUserToken": true,
-    "tokenSetup": {
+    "userAuthentication": {
+      "type": "manual",
       "displayName": "Notion Integration Token",
       "instructions": "Create an integration and copy the token",
       "helpUrl": "https://www.notion.so/my-integrations"
@@ -174,9 +182,33 @@ Some MCP servers are better to use with each users having their own integration
   }
 }
 ```
+After authenticating, the user will be directed to the `/my/tokens` page to enter their token.
+
+### Service OAuth Flow
 
-After the initial OAuth authentication, when users try to use Claude.ai with the integration they will be prompted to
-provide a token via the `/my/tokens` web UI.
+For services that support OAuth, `mcp-front` can handle the entire flow automatically. After the user logs in with Google, they will be shown an interstitial page where they can connect to each service.
+
+**Configuration:**
+```json
+{
+  "stainless": {
+    "transportType": "stdio",
+    "command": "stainless",
+    "args": ["mcp"],
+    "requiresUserToken": true,
+    "userAuthentication": {
+      "type": "oauth",
+      "displayName": "Stainless",
+      "clientId": {"$env": "STAINLESS_OAUTH_CLIENT_ID"},
+      "clientSecret": {"$env": "STAINLESS_OAUTH_CLIENT_SECRET"},
+      "authorizationUrl": "https://api.stainless.com/oauth/authorize",
+      "tokenUrl": "https://api.stainless.com/oauth/token",
+      "scopes": ["mcp:read", "mcp:write"]
+    }
+  }
+}
+```
+This provides a seamless experience for the user and enables automatic token refreshes.
 
 ### Full configuration example
 

cmd/mcp-front/main.go

@@ -1,14 +1,15 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
 	"flag"
 	"fmt"
 	"os"
 
+	"github.com/dgellow/mcp-front/internal"
 	"github.com/dgellow/mcp-front/internal/config"
 	"github.com/dgellow/mcp-front/internal/log"
-	"github.com/dgellow/mcp-front/internal/server"
 )
 
 var BuildVersion = "dev"
@@ -151,12 +152,19 @@ func main() {
 		os.Exit(1)
 	}
 
-	log.LogInfoWithFields("main", "Starting mcp-front", map[string]interface{}{
+	log.LogInfoWithFields("main", "Starting mcp-front", map[string]any{
 		"version": BuildVersion,
 		"config":  *conf,
 	})
 
-	err = server.Run(cfg)
+	ctx := context.Background()
+	mcpFront, err := internal.NewMCPFront(ctx, cfg)
+	if err != nil {
+		log.LogError("Failed to create MCP proxy: %v", err)
+		os.Exit(1)
+	}
+
+	err = mcpFront.Run()
 	if err != nil {
 		log.LogError("Failed to start server: %v", err)
 		os.Exit(1)

config-oauth.json

@@ -32,7 +32,8 @@
     "notion": {
       "transportType": "stdio",
       "requiresUserToken": true,
-      "tokenSetup": {
+      "userAuthentication": {
+        "type": "manual",
         "displayName": "Notion Integration Token",
         "instructions": "Create an integration at https://www.notion.so/my-integrations and copy the token",
         "helpUrl": "https://developers.notion.com/docs/create-a-notion-integration"
@@ -55,6 +56,24 @@
         "-v", "/repos:/repos:ro",
         "mcp/git:latest"
       ]
+    },
+    "stainless": {
+      "transportType": "stdio",
+      "command": "stainless",
+      "args": ["mcp"],
+      "requiresUserToken": true,
+      "userAuthentication": {
+        "type": "oauth",
+        "displayName": "Stainless",
+        "clientId": {"$env": "STAINLESS_OAUTH_CLIENT_ID"},
+        "clientSecret": {"$env": "STAINLESS_OAUTH_CLIENT_SECRET"},
+        "authorizationUrl": "https://api.stainless.com/oauth/authorize",
+        "tokenUrl": "https://api.stainless.com/oauth/token",
+        "scopes": ["mcp:read", "mcp:write"]
+      },
+      "env": {
+        "STAINLESS_API_TOKEN": {"$userToken": "{{token}}"}
+      }
     }
   }
 }

config-user-tokens-example.json

@@ -28,7 +28,8 @@
         "OPENAPI_MCP_HEADERS": {"$userToken": "{\"Authorization\": \"Bearer {{token}}\"}"}
       },
       "requiresUserToken": true,
-      "tokenSetup": {
+      "userAuthentication": {
+        "type": "manual",
         "displayName": "Notion API Token",
         "instructions": "Enter your Notion API token. You can find this at https://www.notion.so/my-integrations",
         "helpUrl": "https://developers.notion.com/docs/authorization",
@@ -43,7 +44,8 @@
         "GITHUB_TOKEN": {"$userToken": "{{token}}"}
       },
       "requiresUserToken": true,
-      "tokenSetup": {
+      "userAuthentication": {
+        "type": "manual",
         "displayName": "GitHub Personal Access Token",
         "instructions": "Create a personal access token at https://github.com/settings/tokens",
         "helpUrl": "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token",

docs-site/src/content/docs/api-reference.md

@@ -138,6 +138,34 @@ Returns:
 }
 ```
 
+## User Service Endpoints
+
+Browser-only endpoints for service connections. Require browser SSO session.
+
+### `GET /oauth/services`
+
+Service connection page. Lists OAuth-enabled services, shown after Google login if services need auth.
+
+### `GET /my/tokens`
+
+Token management. Connect OAuth services, add manual tokens.
+
+### `GET /oauth/connect?service={service_name}`
+
+Initiate OAuth flow. Redirects to service.
+
+### `POST /oauth/disconnect`
+
+Revoke OAuth connection. Form: `service={service_name}`.
+
+### `POST /my/tokens/set`
+
+Save manual token. Form: `service={service_name}&token={user_token}`.
+
+### `GET /oauth/callback/{service_name}`
+
+OAuth callback. Set as redirect URI in service OAuth config.
+
 ## Authentication
 
 ### Bearer token
@@ -159,19 +187,4 @@ PKCE is required for all OAuth flows.
 
 ## Errors
 
-All errors follow OAuth 2.1 format:
-
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Missing required parameter"
-}
-```
-
-Common errors:
-
-- `invalid_request` - Bad parameters
-- `invalid_client` - Unknown client
-- `invalid_grant` - Bad auth code
-- `unauthorized_client` - Client can't use grant type
-- `server_error` - Internal error
+OAuth 2.1 format with `error` and `error_description` fields. Common codes: `invalid_request` (bad parameters), `invalid_client` (unknown client), `invalid_grant` (bad auth code), `unauthorized_client` (client can't use grant type), `server_error` (internal error).