MCP Personal Assistant

# Realistic MCP Authentication Architecture ## 🎯 The Problem We Solved **Original Issue**: The OAuth 2.1 authorization server implementation was technically perfect but practically unusable because: 1. MCP clients (Claude Desktop) don't support OAuth flows 2. MCP servers shouldn't handle user login UIs 3. Users already have accounts with Google, GitHub, etc. **Solution**: Refactored to **token validation architecture** using external identity providers. --- ## 🏗️ New Architecture Overview ### **External Provider → Token Validation Flow** ``` User → Google/Auth0/GitHub → Access Token → MCP Server → Token Validation → User Context (Login) (Client Gets) (Validates) (Creates Session) ``` **Key Components:** 1. **External Identity Providers**: Handle user authentication 2. **Token Validation Service**: Validates external tokens 3. **MCP User Context**: Internal user representation 4. **Multi-tenant Isolation**: Automatic tenant separation --- ## 🔐 Supported Identity Providers ### **1. Google OAuth 2.0** (Recommended) ```python # Configuration MCP_HTTP_GOOGLE_CLIENT_ID=your-app.googleusercontent.com MCP_HTTP_GOOGLE_CLIENT_SECRET=optional-client-secret # Token Validation - ID Tokens (JWT): Full verification with Google's JWKS - Access Tokens: Validation via Google UserInfo API - User Data: email, name, picture, email_verified ``` ### **2. Auth0** (Best Developer Experience) ```python # Configuration MCP_HTTP_AUTH0_DOMAIN=your-app.auth0.com MCP_HTTP_AUTH0_AUDIENCE=https://your-mcp-api.com # Features - Multiple providers in one: Google, Apple, GitHub, Microsoft - Hosted login pages - Enterprise SSO integration - Custom user metadata ``` ### **3. GitHub OAuth** (Developer-Focused) ```python # Configuration MCP_HTTP_GITHUB_ENABLED=true # Perfect for: - Developer tools - Open source projects - Technical user base - Simple setup (no client secrets needed) ``` ### **4. API Keys** (Service-to-Service) ```python # Configuration MCP_HTTP_API_KEY=your-service-api-key # Use Cases: - Server-to-server integration - CI/CD pipelines - Automated tools - Simple authentication fallback ``` --- ## 🚀 Practical Implementation ### **User Authentication Flow** **Step 1: User Login (External)** ```javascript // User clicks "Login with Google" in client app const token = await googleAuth.getAccessToken(); ``` **Step 2: Token Validation (MCP Server)** ```python # MCP server validates external token user_context = await token_validator.validate_token( token=bearer_token, provider_hint="google" ) # Creates MCPUserContext: # - user_id: "google:123456789" # - tenant_id: "gmail_com" # - permissions: ["read", "write"] ``` **Step 3: MCP Operations** ```python # All subsequent MCP operations use validated context @app.post("/mcp/tools/call") async def call_tool(request: Request): user: MCPUserContext = request.state.user db = await get_tenant_database(user.tenant_id) # ... tenant-isolated operations ``` --- ## 🏢 Multi-Tenancy ### **Automatic Tenant Isolation** ```python # Email domain → Tenant mapping tenant_mapping = { "mycompany.com": "company_tenant", "gmail.com": "personal_users", "outlook.com": "personal_users" } # User with alice@mycompany.com → company_tenant # User with bob@gmail.com → personal_users ``` ### **Database Isolation** ```python # PostgreSQL schema-based isolation async def get_tenant_database(tenant_id: str): return await connect_to_schema(f"tenant_{tenant_id}") # Each tenant gets isolated: # - Projects, todos, documents # - Vector embeddings # - Audit logs ``` --- ## 🔧 Easy Setup Options ### **Option 1: Google OAuth (Simplest)** ```bash # 1. Create Google OAuth app # 2. Set environment variables export MCP_HTTP_GOOGLE_CLIENT_ID="123.googleusercontent.com" export MCP_HTTP_DATABASE_CONNECTION_STRING="postgresql://..." # 3. Run server python -m src.servers.http_server ``` ### **Option 2: Auth0 (Most Flexible)** ```bash # 1. Create Auth0 application # 2. Configure providers (Google, Apple, GitHub) export MCP_HTTP_AUTH0_DOMAIN="myapp.auth0.com" export MCP_HTTP_AUTH0_AUDIENCE="https://my-mcp-api.com" # 3. Run server with multiple providers python -m src.servers.http_server ``` ### **Option 3: Development Mode** ```bash # No external auth needed export MCP_HTTP_ENVIRONMENT="development" export MCP_HTTP_API_KEY="dev-key-123" # Uses API key authentication python -m src.servers.http_server ``` --- ## 📱 Client Integration ### **Current Reality: API Keys** ```json // Claude Desktop config (current limitation) { "mcpServers": { "personal-assistant": { "command": "python", "args": ["-m", "src.servers.local_server"] } } } ``` ### **Future: HTTP with External Auth** ```json // When MCP clients support HTTP (future) { "mcpServers": { "personal-assistant": { "transport": "https", "url": "https://my-mcp-server.com", "auth": { "type": "external_token", "provider": "google" } } } } ``` ### **Workaround: Auth Proxy** ``` Claude Desktop → Local Auth Proxy → HTTPS MCP Server (handles Google OAuth) ``` --- ## 🌐 Deployment Options ### **Railway** (Recommended for MVP) ```bash # 1. Push code to GitHub # 2. Connect Railway to repository # 3. Add PostgreSQL addon # 4. Set environment variables railway deploy ``` ### **Render** ```bash # 1. Connect GitHub repository # 2. Add managed PostgreSQL # 3. Configure environment variables # Auto-deploys on git push ``` ### **Fly.io** ```bash # 1. Install flyctl # 2. Create Postgres app fly postgres create fly deploy ``` ### **Docker** ```bash # Use provided docker-compose.yml docker-compose up -d ``` --- ## 🔒 Security Features ### **Token Security** - ✅ **External token validation** with provider JWKS - ✅ **Token caching** with TTL for performance - ✅ **Provider verification** (issuer, audience, expiry) - ✅ **Graceful token refresh** handling ### **Multi-tenant Security** - ✅ **Database isolation** per tenant - ✅ **API rate limiting** per tenant - ✅ **Audit logging** with tenant context - ✅ **Permission-based access** control ### **Transport Security** - ✅ **HTTPS enforcement** in production - ✅ **HSTS headers** with preload - ✅ **Security headers** (CSP, XSS protection) - ✅ **CSRF protection** for web interfaces --- ## 📊 Comparison: Before vs After | Aspect | Before (Full OAuth Server) | After (Token Validation) | |--------|----------------------------|---------------------------| | **User Auth** | MCP server handles login | External providers handle | | **Token Issuing** | MCP server issues tokens | External providers issue | | **MCP Role** | Authorization server | Resource server | | **Client Support** | Needs OAuth flow support | Works with any HTTP client | | **Setup Complexity** | High (user DB, login UI) | Low (configure providers) | | **Maintenance** | High (auth security) | Low (validate tokens only) | | **User Experience** | Custom login forms | Familiar provider login | --- ## 🎯 Why This Architecture Works ### **✅ Realistic** - Users already have Google/GitHub accounts - No custom login UI needed - External providers handle security updates - MCP clients can eventually add HTTP support ### **✅ Secure** - Battle-tested provider authentication - Token validation with proper verification - Multi-tenant isolation - Comprehensive audit logging ### **✅ Scalable** - Stateless token validation - Database-per-tenant isolation - Horizontal scaling ready - Provider handles auth load ### **✅ Maintainable** - Less auth code to maintain - Provider handles compliance (GDPR, etc.) - Standard OAuth 2.0/OIDC flows - Clear separation of concerns --- ## 🚀 Next Steps 1. **Create server implementations** using this architecture 2. **Add comprehensive tests** for token validation 3. **Deploy to cloud platform** (Railway/Render) 4. **Create client examples** for different auth flows 5. **Document integration guides** for each provider This architecture provides the **best of both worlds**: enterprise-grade security with practical implementation that works with existing identity providers and can evolve as MCP client capabilities improve.