docs: add comprehensive OAuth server states and troubleshooting guide

technicalpickles · technicalpickles · commit 2b301de3447c · 2025-12-01T13:52:35.000-05:00
Enhanced docs/oauth-zero-config.md with detailed documentation for: 1. Server States Section: - Connected states: ready (authenticated), connected (no token) - Waiting states: pending_auth (normal waiting state, not an error) - Transitional states: connecting, authenticating - Error states: disconnected, error 2. Checking Authentication Status: - How to use `mcpproxy auth status` command - Example output with emoji indicators (✅⏳❌) - Status meaning explanations 3. Troubleshooting Section with 4 Common Issues: Issue smart-mcp-proxy#1: Server Shows "Pending Auth" State - Symptoms: ⏳ icon in tray, pending_auth status - Cause: OAuth detected but user hasn't authenticated - Solution: Use `auth login` or tray "Authenticate" action - Clarification: NOT an error, intentional deferral Issue smart-mcp-proxy#2: Authentication Token Expired - Symptoms: Was working, now shows "Auth Failed" - Cause: OAuth token expired (1-24 hour lifetime) - Solution: Re-authenticate with `auth login` Issue smart-mcp-proxy#3: OAuth Detection Not Working - Symptoms: No pending_auth, just connection failures - Diagnosis: Check doctor output, logs, manual OAuth test - Common causes: Non-standard endpoints, firewall issues - Solution: Add explicit OAuth configuration Issue smart-mcp-proxy#4: OAuth Login Opens Browser But Fails - Symptoms: Browser opens, approval given, but still fails - Diagnosis: Check callback logs for authorization code - Common causes: Port conflict, timeout, firewall - Solution: Retry with debug logging 4. Diagnostic Commands Reference: - doctor: Quick OAuth detection check - auth status: View token status - upstream list: Check connection status - upstream logs: View OAuth flow logs - auth login --log-level=debug: Test with debug output - upstream list --format=json | jq: Verify OAuth config This addresses user confusion about "Pending Auth" being displayed as an error state. Documentation now clearly explains it's a normal waiting state and provides step-by-step troubleshooting for all OAuth-related issues. Related to PR smart-mcp-proxy#165: Zero-config OAuth with RFC 8707 support Task: Update documentation for OAuth server states and troubleshooting
diff --git a/docs/oauth-zero-config.md b/docs/oauth-zero-config.md
@@ -38,10 +38,175 @@ For non-standard OAuth requirements:
 
 See design document: `docs/designs/2025-11-27-zero-config-oauth.md`
 
+## Server States
+
+OAuth-capable servers in MCPProxy can be in one of these states:
+
+### Connected States
+- **`ready`**: Server connected and authenticated (has valid, non-expired OAuth token)
+- **`connected`**: Server connected but not OAuth-authenticated (no token or expired token)
+
+### Waiting States
+- **`pending_auth`**: OAuth authentication required but deferred (waiting for user action)
+  - Occurs when OAuth server detected but user hasn't logged in yet
+  - Server shows ⏳ icon in tray UI
+  - Use `mcpproxy auth login --server=<name>` to authenticate
+  - **Not an error** - this is a normal waiting state
+
+### Transitional States
+- **`connecting`**: Server is attempting to connect
+- **`authenticating`**: OAuth authentication flow in progress
+
+### Error States
+- **`disconnected`**: Server failed to connect (check logs for details)
+- **`error`**: Unexpected error occurred (check `last_error` field)
+
+## Checking Authentication Status
+
+Use the `auth status` command to view OAuth authentication state for all servers:
+
+```bash
+mcpproxy auth status
+```
+
+**Example output:**
+```
+Server                   Status              Token Expiry           Authenticated
+────────────────────────────────────────────────────────────────────────────────
+slack-server            ✅ Authenticated     2025-12-01 15:30:00   Yes
+github-server           ⏳ Pending Auth      -                      No
+sentry-server           ❌ Auth Failed       Token expired          No
+```
+
+**Status meanings:**
+- **✅ Authenticated**: Valid OAuth token, server ready to use
+- **⏳ Pending Authentication**: Waiting for OAuth login (use `auth login`)
+- **❌ Authentication Failed**: OAuth token invalid or expired (re-authenticate required)
+
 ## Troubleshooting
 
+### Common Issues
+
+#### 1. Server Shows "Pending Auth" State
+
+**Symptoms:**
+- Server appears with ⏳ icon in tray UI
+- `mcpproxy upstream list` shows `pending_auth` status
+- `mcpproxy auth status` shows "⏳ Pending Authentication"
+
+**Cause:** OAuth-capable server detected, but user hasn't authenticated yet.
+
+**Solution:**
+```bash
+# Option 1: CLI authentication
+mcpproxy auth login --server=<server-name>
+
+# Option 2: Tray UI (recommended)
+# Right-click tray icon → <server-name> → "Authenticate"
+```
+
+**Why this happens:** MCPProxy automatically detects OAuth requirements from server responses. The server is intentionally deferred (not an error) to prevent blocking daemon startup.
+
+#### 2. Authentication Token Expired
+
+**Symptoms:**
+- Server was working, now shows "❌ Auth Failed"
+- `auth status` shows "Token expired"
+- Server `authenticated` field is `false`
+
+**Cause:** OAuth access token expired (typical lifetime: 1-24 hours).
+
+**Solution:**
+```bash
+# Re-authenticate to get new token
+mcpproxy auth login --server=<server-name>
+```
+
+**Prevention:** MCPProxy automatically refreshes tokens when possible. If auto-refresh fails, manual re-authentication is required.
+
+#### 3. OAuth Detection Not Working
+
+**Symptoms:**
+- Server requires OAuth but shows as disconnected
+- No "Pending Auth" state, just repeated connection failures
+- Logs show generic connection errors
+
+**Diagnosis:**
 ```bash
-./mcpproxy doctor              # Check OAuth detection
-./mcpproxy auth status         # View OAuth-capable servers
-./mcpproxy auth login --server=myserver --log-level=debug
+# Check if server is OAuth-capable
+mcpproxy doctor
+
+# Enable debug logging to see OAuth detection
+mcpproxy upstream logs <server-name> --tail=100
+
+# Test OAuth flow manually with debug logs
+mcpproxy auth login --server=<server-name> --log-level=debug
+```
+
+**Common causes:**
+- Server doesn't return proper 401 with `WWW-Authenticate` header
+- Server uses non-standard OAuth endpoints (need manual config)
+- Network/firewall blocking OAuth metadata endpoint
+
+**Solution:** Add explicit OAuth configuration:
+```json
+{
+  "name": "custom-server",
+  "url": "https://api.example.com/mcp",
+  "oauth": {
+    "client_id": "your-client-id",
+    "client_secret": "your-client-secret",
+    "auth_url": "https://oauth.example.com/authorize",
+    "token_url": "https://oauth.example.com/token",
+    "scopes": ["mcp.read", "mcp.write"]
+  }
+}
+```
+
+#### 4. OAuth Login Opens Browser But Fails
+
+**Symptoms:**
+- Browser opens with OAuth prompt
+- After approving, shows "Success" page
+- But server still shows "Pending Auth" or "Auth Failed"
+
+**Diagnosis:**
+```bash
+# Check if callback server received authorization code
+mcpproxy upstream logs <server-name> --tail=50 | grep -i "oauth\|callback"
+```
+
+**Common causes:**
+- Callback server port conflict (rare with dynamic allocation)
+- OAuth callback timeout (took > 5 minutes to approve)
+- Network/firewall blocking loopback connections
+
+**Solution:**
+```bash
+# Retry with extended timeout and debug logging
+mcpproxy auth login --server=<server-name> --log-level=debug
+
+# If persistent, check firewall rules for 127.0.0.1 loopback
+```
+
+### Diagnostic Commands
+
+```bash
+# Quick OAuth detection check
+mcpproxy doctor
+
+# View all OAuth-capable servers and token status
+mcpproxy auth status
+
+# Check server connection status
+mcpproxy upstream list
+
+# View OAuth flow logs for specific server
+mcpproxy upstream logs <server-name> --tail=100 --follow
+
+# Test OAuth authentication with debug output
+mcpproxy auth login --server=<server-name> --log-level=debug
+
+# Verify OAuth configuration extraction
+mcpproxy upstream list --format=json | jq '.[] | select(.name=="<server-name>") | .oauth'
 ```
